User Tools

Site Tools


oak:tutorials:particle-function

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
oak:tutorials:particle-function [2016/03/24 16:32]
jwhendy
oak:tutorials:particle-function [2016/05/27 01:30] (current)
pfeerick edited to hopefully reduce confusion on how Particle.function is used in code
Line 1: Line 1:
-**In progress!** +===== Oak: using Particle.function() =====
- +
-This is currently a copy of particle-variable to use as a template. +
- +
------ +
- +
-===== Oak: using Particle.variable() ===== +
- +
-[[http://​digistump.com/​wiki/​_media/​oak-rgb-led.png|{{http://​digistump.com/​wiki/​_media/​oak-rgb-led.png?​400}}]]+
  
 This tutorial is very similar to the one on [[http://​digistump.com/​wiki/​oak/​tutorials/​particle-variable|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. This tutorial is very similar to the one on [[http://​digistump.com/​wiki/​oak/​tutorials/​particle-variable|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.
Line 24: Line 16:
 |Resistor, 220 ohm| 3 | Red-Red-Brown| |Resistor, 220 ohm| 3 | Red-Red-Brown|
  
-These are the same components used with the [[http://​digistump.com/​wiki/​oak/​tutorials/​rgb-led#​components_used|advanced ​LED tutorial]]. Feel free to substitute any resistor value between 100-1k ohms.+These are the same components used with the [[http://​digistump.com/​wiki/​oak/​tutorials/​rgb-led#​components_used|RGB LED tutorial]]. Feel free to substitute any resistor value between 100-1k ohms.
  
 **Note:** You need to install [[https://​curl.haxx.se/​download.html|curl]] to push data to the Particle API. **Note:** You need to install [[https://​curl.haxx.se/​download.html|curl]] to push data to the Particle API.
Line 34: Line 26:
 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. 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:+The syntax looks like ''​Particle.function("​name",​ function_name)'',​ and you then have a function that look like the below example, which is run when the function is triggered. You would normally place the ''​Particle.function''​ command in the setup() portion of your code. Have a look at the example sketch at the bottom of the page to better understand how function is used.
  
 <​code>​ <​code>​
-Particle.function("​name",​ function_name) 
- 
 int function_name(String arg) int function_name(String arg)
 { {
Line 195: Line 185:
  
 Thankfully there are ways to split apart a ''​String''​ if you know the structure. There are several examples of various ways to pass multiple values to ''​Particle.function()''​ if you [[https://​www.google.com/​webhp?​sourceid=chrome-instant&​ion=1&​espv=2&​ie=UTF-8#​q=pass%20multiple%20parameters%20to%20particle.function|search for them]]. We will use the one described [[https://​community.particle.io/​t/​rest-api-arguments-is-there-a-better-way/​960/​2|here]]. Thankfully there are ways to split apart a ''​String''​ if you know the structure. There are several examples of various ways to pass multiple values to ''​Particle.function()''​ if you [[https://​www.google.com/​webhp?​sourceid=chrome-instant&​ion=1&​espv=2&​ie=UTF-8#​q=pass%20multiple%20parameters%20to%20particle.function|search for them]]. We will use the one described [[https://​community.particle.io/​t/​rest-api-arguments-is-there-a-better-way/​960/​2|here]].
 +
 +<​code>​
 +// each color'​s brightness
 +int bright_r = 0;
 +int bright_g = 0;
 +int bright_b = 0;
 +
 +// locations of the commas we'll find below
 +int loc1 = 0;
 +int loc2 = 0;
 +int loc3 = 0;
 +
 +void setup()
 +{                ​
 +
 +  // just one function!
 +  Particle.function("​set",​ set_rgb);
 +  ​
 +  // initialize each color pin as an output
 +  pinMode(6, OUTPUT);
 +  pinMode(7, OUTPUT);
 +  pinMode(8, OUTPUT);
 +  ​
 +}
 +
 +int set_rgb(String arg)
 +{
 +
 +  // find the location of the first comma
 +  // extract from 0 to the comma, storing the value
 +  // as an integer
 +  loc1 = arg.indexOf(","​);​
 +  bright_r = arg.substring(0,​ loc1).toInt();​
 +
 +  // find the next comma by searching starting at the last one
 +  // extract from the last comma to this one
 +  // store as an integer in bright_g
 +  loc2 = arg.indexOf(",",​loc1+1);​
 +  bright_g = arg.substring(loc1+1,​ loc2).toInt();​
 +
 +  // repeat, taking the value between the last comma and this one
 +  loc3 = arg.indexOf(",",​loc2+1);​
 +  bright_b = arg.substring(loc2+1,​ loc3).toInt();​
 +
 +  // write all three values to their respective color pins
 +  analogWrite(6,​ bright_r);
 +  analogWrite(7,​ bright_g);
 +  analogWrite(8,​ bright_b);
 +  ​
 +}
 +
 +void loop()
 +
 +}
 +</​code>​
 +
 +With only one function that can extract three values separated by commas, we can now pass an ''​r,​g,​b''​ formatted argument and have all three colors changed in one shot:
 +
 +<​code>​
 +curl https://​api.particle.io/​v1/​devices/​id_goes_here/​set \
 +    -d access_token=token_goes_here
 +    -d "​args=1023,​0,​512"​
 +</​code>​
 +
 +That will turn on red all the way and blue halfway, creating a pinkish color. Play around with other value combinations and set some colors!
  
 ===== Conclusion ===== ===== Conclusion =====
  
-And that's it for the basics of sending data with ''​curl''​ via particle.io! It's up to you what you send, and how you have the Oak respond to it. For one idea, check out the tutorial on using ''​python''​ to generate or collect data (say, from a local sensor) and send it to the Oak. The nice thing with these functions is that if you can do something on the Oak, you can make it happen when a command is sent with ''​Particle.function()'';​ it's just a matter of slightly re-arranging your code.+And that's it for the basics of sending data with ''​curl''​ via particle.io! ​We learned how to pass values, as well as to utilize one ''​Particle.function()''​ to set many values by sending them in a known format, combined with ''​indexOf''​ and ''​substring()''​ to separate them from one another.  
 + 
 +It's up to you what you send, and how you have the Oak respond to it. For one idea, check out the tutorial on using ''​python''​ to generate or collect data (say, from a local sensor) and send it to the Oak. The nice thing with these functions is that if you can do something on the Oak, you can make it happen when a command is sent with ''​Particle.function()'';​ it's just a matter of slightly re-arranging your code.
oak/tutorials/particle-function.1458862332.txt.gz · Last modified: 2016/03/24 16:32 by jwhendy