This is an old revision of the document!
In progress!
This is currently a copy of particle-variable to use as a template.
This tutorial is very similar to the one on Particle.variable(). This time, however we will be doing the reverse: sending data to the Oak. To accomplish this, we use Particle.function()
. As an example, we will send POST
commands using curl
to the Particle API which will control the color of an RGB led connected to the Oak.
In addition to this tutorial, please do take a look at the official documentation.
Part | Quantity | Identification |
---|---|---|
Oak with soldered headers | 1 | |
Breadboard | 1 | |
Jumper wires | 4 | |
RGB LED | 1 | whitish LED with 4 leads, one longer than the others |
Resistor, 220 ohm | 3 | Red-Red-Brown |
These are the same components used with the advanced LED tutorial.
Note: You need to install curl to push data to the Particle API.
This function creates an interface between your Oak and particle.io. We create a function with a given name, and then access that named function via curl
commands, passing along a value with it. On the Oak side, it finds the function with that name, and then runs it with the value that was passed.
The syntax looks like this:
Particle.function("name", function_name) int function_name(String arg) { // code goes here Serial.print(arg); }
We would access this function like this:
curl https://api.particle.io/v1/devices/id_goes_here/name/ \ -d access_token=token_goes_here -d "args=hello"
The Oak would print “hello” when this curl
command is sent (which puts name
from above in the URL, not function_name). When the Oak receives the call to name
, it runs the associated function (function_name
), and passes along a String
(and only a String
) which we called arg
. This might seem complicated, but it's fairly straightforward. Let's connect a circuit and test it out!
Please complete the circuit used in the RGB LED tutorial.
The following code will create Particle.function()
s in order to allow setting of each channel of an RGB LED:
todo
This is the circuit we will begin with, which is explained in the tutorial on buttons.
Additionally, we will recreate the circuit from the tutorial on photocells to read an analog sensor value.
Here is the code we will start with:
// 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); } }
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:
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 command below, replacing id_here
and token_here
with the appropriate values. Alternatively, put the URL below into a browser:
$ curl https://api.particle.io/v1/devices/id_here/button?access_token=token_here
This is the response:
$ 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.
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 this tutorial.
Here is the code we will use:
// 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); }
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 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.