===== Oak: using Particle.variable() =====

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 [[https://www.particle.io/|particle.io]] for reading data from the Oak. The basic idea is pretty simple, and we'll start with a simple push button. Review the [[oak:tutorials:button|tutorial on buttons]] for a refresher if you'd like. In addition, please do take a look at the [[https://docs.particle.io/reference/firmware/core/#particle-variable-|official documentation]].

===== Components used =====

^ Part       ^ Quantity          ^Identification^
| Oak with soldered headers |1| |
| Breadboard| 1| |
| Photocell | 1 | |
| Push button | 1 | |
| Jumper wires | 3 | |
| Resistor, 10k ohm |1| Brown-Black-Orange|

**Note:** Optionally, you can install [[https://curl.haxx.se/download.html|curl]] to get data from the Particle API, however pasting the links into a browser works just as well.

===== Concepts =====

=== Particle.variable() ===

This function creates an interface between a variable on your Oak and particle.io. Each time the variable changes, the Oak will update the value stored in the Particle cloud, which you can then access with a call to a website (produced by visiting the page in the browser, or issuing a command using ''curl'').

The ''Particle.variable()'' function takes two parameters: the name of the variable in the Particle cloud, and the name of the local variable stored on the Oak. For example ''Particle.variable("particle_name", oak_name)''. The value on the Oak would be stored in the variable ''oak_var''. When accessing this variable via the Particle API, you would use the following:

<code>curl https://api.particle.io/v1/devices/id_here/particle_name?access_token=token_here</code>

===== Circuit =====


=== Button ===
This is the circuit we will begin with, which is explained in the [[http://digistump.com/wiki/oak/tutorials/button|tutorial on buttons]].

[[http://digistump.com/wiki/_media/oak/tutorials/button-pullup.png|{{http://digistump.com/wiki/_media/oak/tutorials/button-pullup.png?400}}]]


=== Photocell ===

Additionally, we will recreate the circuit from the [[http://digistump.com/wiki/oak/tutorials/photocell|tutorial on photocells]] to read an analog sensor value.

[[http://digistump.com/wiki/_media/oak/tutorials/photocell.png|{{http://digistump.com/wiki/_media/oak/tutorials/photocell.png?400}}]]

[[http://digistump.com/wiki/_media/oak/tutorials/photocell-wiring.jpg|{{http://digistump.com/wiki/_media/oak/tutorials/photocell-wiring.jpg?400}}]]


===== Code =====

=== Reading a button ===

Here is the code we will start with:

<code>
// variable to store the push button digitalRead() value
int button;

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 variable 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); }

}
</code>

Notice that the only additional code other than reading the button is to attach a "cloud name" to the variable so that we can read it from the web. After uploading the code above, press the button to check that the on-board LED illuminates:

[[http://digistump.com/wiki/_media/oak/tutorials/button-led-off.jpg|{{oak:tutorials:button-led-off.jpg?300 }}]]
[[http://digistump.com/wiki/_media/oak/tutorials/button-led-on.jpg|{{ oak:tutorials:button-led-on.jpg?310 }}]]

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 [[oak:tutorials:particle-id-token|Particle API wiki entry]]. If you have ''curl'' installed, open a command prompt/terminal, and type the command below, replacing ''id_here'' and ''token_here'' with the appropriate values. Alternatively, put the URL below into a browser:

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

This is the response:

<code>
$ 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
  }
</code>

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:

<code>
$ 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
  }
</code>

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.

=== Code: reading a photoresistor ===

The only difference in the next example is that instead of a button, we will be reading the analog signal from a photoresistor, just as described in [[http://digistump.com/wiki/oak/tutorials/photocell|this tutorial]].

Here is the code we will use:

<code>
// variable to store our reading
int light;

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);

}
</code>

Now we can call the URL

<code>

$ 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
  }
}
</code>

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

===== Conclusion =====

And that's it for the basics of getting data via particle.io! It's up to you how you get the data and what you do with it. The sky is the limit. 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.