User Tools

Site Tools


oak:tutorials:particle-variable

This is an old revision of the document!


So, you've got an Oak all set up and ready to go. Now it's time to put its wireless abilities to work! This lesson will introduce Particle.variable() a method provided by particle.io for reading data from the Oak. The basic idea is pretty simple, and we'll start with a simple push button. Feel free to review the tutorial on buttons for a refresher. In addition, please do take a look at the official documentation.

Requirements

This lesson will use (in addition to an Oak):

  • a tactile push button
  • a photoresistor
  • jumper wires
  • a breadboard
  • a resistor (10k ohms is good)

Optionally, you can install curl to get data from the Particle API, however pasting the links into a browser works just as well.

Example: getting the state of a button

Here's the circuit we'll use, which reads the button (pulled up to Vcc through a 10k resistor) on pin 10:

The code we'll start with is as follows:

int button;

// the setup() loop sets pinModes, starts things like Serial,
// and is run once when the Oak powers on
void setup()
{                

  // use the on-board LED to illuminate when the button is pressed
  pinMode(1, OUTPUT);
  
  // initialize the digital pin as an input
  pinMode(10, INPUT);

  // Particle.variable() takes two options:
  // 1) the name of the varialbe to access in the GET request
  // 2) the name of the local variable that holds the value to report
  Particle.variable("button", button);

}


// the loop() routine runs over and over again
void loop()
{

  button = digitalRead(10);

  // for debugging, it's helpful to have a way to know
  // that the button is being reported properly

  if(button == HIGH) {digitalWrite(1, HIGH); }
  if(button == LOW) { digitalWrite(1, LOW); }

}

The only thing we did other than reading a button as usual is to attach Particle.variable() to that variable and give it a name we can use through the web to access the value. After uploading the code above, press the button to check that the on-board LED illuminates:

button-led-off.jpg button-led-on.jpg

This confirms that the variable button is being read correctly. Next, make sure you have your device_id and access_token as described in the Particle API wiki entry.

If you have curl installed, open a command prompt/terminal, and type the following (replacing id_here and token_here with the appropriate values). Otherwise, type out the URL somewhere you can copy/paste from, and visit that page in a browser.

$ curl https://api.particle.io/v1/devices/id_here/button?access_token=token_here

Hopefully this is what you get in return!

$ curl https://api.particle.io/v1/devices/id_here/button?access_token=token_here
{
  "cmd": "VarReturn",
  "name": "button",
  "result": 1,
  "coreInfo": {
    "last_app": "",
    "last_heard": "2016-03-19T20:51:18.623Z",
    "connected": true,
    "last_handshake_at": "2016-03-19T20:32:30.268Z",
    "deviceID": "12345678",
    "product_id": 82
  }

Neat, huh? Keep in mind that we're pulling the button up to Vcc, so it's non-pressed state reads HIGH, or 1. If we press it and re-run the curl command/paste into a browser, we get back the following:

$ curl https://api.particle.io/v1/devices/id_here/button?access_token=token_here
{
  "cmd": "VarReturn",
  "name": "button",
  "result": 0,
  "coreInfo": {
    "last_app": "",
    "last_heard": "2016-03-19T20:51:30.817Z",
    "connected": true,
    "last_handshake_at": "2016-03-19T20:32:30.268Z",
    "deviceID": "12345678",
    "product_id": 82
  }

Note that the contents in result changed. Since the data is sent in json format, you can use any number of methods to query the above URL, extract the contents of result, and do something based on that value.

Example: getting the brightness from a photoresistor

From a code standpoint, this example is nearly identical to the above. The difference is that we will be reading the analog signal from a photoresistor. For some great background information, Adafruit has a nice writeup on photoresistors. Here's how we'll wire up our circuit:

In pictures:

photocell-wiring.jpg

To read the photoresistor, we use this code:

// variable to store our reading
int light;

// the setup() loop sets pinModes, starts things like Serial,
// and is run once when the Oak powers on
void setup()
{                

  // use the on-board LED to illuminate when the button is pressed
  pinMode(1, OUTPUT);
  
  // initialize the analog pin as an input
  pinMode(A0, INPUT);

  // Particle.variable() to access this from the cloud
  Particle.variable("light", light);

}


// the loop() routine runs over and over again
void loop()
{

  // take a reading
  light = analogRead(A0);

  // if the photocell is covered (dark, resistance is low)
  // turn the on-board LED light on. Otherwise, turn it off.
  if(light < 250) { digitalWrite(1, HIGH); }
  if(light > 250) { digitalWrite(1, LOW); }
  delay(25);

}

Now we can call the URL

$ curl https://api.particle.io/v1/devices/id_here/light?access_token=token_here
{
  "cmd": "VarReturn",
  "name": "light",
  "result": 785,
  "coreInfo": {
    "last_app": "",
    "last_heard": "2016-03-20T04:13:23.389Z",
    "connected": true,
    "last_handshake_at": "2016-03-20T04:13:15.370Z",
    "deviceID": "12345678",
    "product_id": 82
  }

$ curl https://api.particle.io/v1/devices/id_here/light?access_token=token_here
{
  "cmd": "VarReturn",
  "name": "light",
  "result": 193,
  "coreInfo": {
    "last_app": "",
    "last_heard": "2016-03-20T04:13:27.820Z",
    "connected": true,
    "last_handshake_at": "2016-03-20T04:13:15.370Z",
    "deviceID": "12345678",
    "product_id": 82
  }
}

In addition the on-board LED turns on when the cell is covered, as the analog reading drops below 250.

And that's it for the basics of getting data via particle.io! It's up to you how you get the data (curl as above, javascript in a web page, or some other means) and what you do with it (say, a sensor that can notify you when it's dark somewhere), so the sky is the limit for what else you come up with. Keep in mind that the lessons above are transferable to any sensor. If you can read the data, you can make it available in the cloud for access.

oak/tutorials/particle-variable.1458447894.txt.gz · Last modified: 2016/03/19 21:24 by jwhendy