Digistump Wiki

In this example, we'll show one way you can make the data sent by the Oak useful with python. You can install python as described in the firmware over serial tutorial. Make sure for the below that you're using python version 2.x (e.g. 2.7), not python v3.

Note: The potentiometer, Arduino, and jumpers are for the purpose of reading the output of a serial device and sending it through python. These are not necessary to send data with python, they're serving as a “data generator” as an example of a potential use.

To verify your python environment, open a Command Prompt or terminal and type python and press enter. If python is working properly, you should enter a session:

Python 2.7.11 (default, Mar  3 2016, 11:00:04) 
[GCC 5.3.0] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> 

If that happens, you're all set! If not, you should get python in order before proceding. Type quit() and press enter to quit this session.

python is a programming language. It offers a wide range of capabilities through “modules” which can be imported. Since it has wide adoption as a good general programming language and is relatively fast, it is used in many academic and industrial fields. The modules make it very easy to do certain tasks without having to write the code yourself.

For some examples, it is easy to send data to the web with the module requests and easy to read in serial data using pyserial. Since you will often want to use a computer of some sort to act on the data you collect with the Oak, knowing a little about how to program is a a useful skill. python works very well on the Raspberry Pi, which could serve as one way to have a computer on at all times talking to the Oak.

This tutorial will use two circuits:

Replicate the RGB LED setup in this tutorial.

Optionally, create this circuit on an Arduino:

We will re-use the code from the tutorial on Particle.function(). We just want the Oak listening for an RGB string of data, which it will then use to set the color of the LED.

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

// break the r,g,b string into three separate values
int set_rgb(String arg)
{

  loc1 = arg.indexOf(",");
  bright_r = arg.substring(0, loc1).toInt();

  loc2 = arg.indexOf(",",loc1+1);
  bright_g = arg.substring(loc1+1, loc2).toInt();

  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()
{ 
}

Save this file as py-particle-function.py. There are several ways to send data via POST to a URL; this one was found as a recommendation in the particle.io forums.

import requests

device_id = 'device_id'
access_token = 'token'
args = '1023,1023,1023'

r = requests.post('https://api.particle.io/v1/devices/%s/set' % device_id, \
                  data={'args': args, 'access_token':access_token})

print (r.text)

Run the above with this command, after entering your device_id and access_token:

$ python ./py-particle-function.py

Your LED should turn on full white, and you will see this response:

{
  "id": "12345678",
  "last_app": "",
  "connected": true,
  "return_value": 1073
}

Change the values in the python file and re-run it. You can now use a programming language to send data to your Oak!

In this next example, we will use an Aruino as a data generator by reading in the value of a potentiometer with python and the setting the color of our LED based on it's value. Here is the code to send the potentiometer value over serial:

// define a variable to hold the value read
// define a variable to hold the value read and the colors
int pot = 0;
int r = 0;
int g = 0;
int b = 0;

void setup()
{
  // begin a serial interface
  Serial.begin(9600);
}

void loop() {

  // read the value of pin A0, store it in the variable, pot
  pot = analogRead(A0);

  // this next set of statements maps the 0-1023 reading of the potentiometer
  // to a definition for a given color. It is based on this RGB/HSV map:
  // https://github.com/FastLED/FastLED/wiki/Pixel-reference
  r = constrain(map(pot, 0, 385, 1023, 0), 0, 1023);
  if(pot > 640) { r = constrain(map(pot, 640, 1023, 0, 1023), 0, 1023); }
  
  g = constrain(map(pot, 0, 385, 0, 1023), 0, 1023);
  if(pot > 385) { g = constrain(map(pot, 385, 640, 1023, 0), 0, 1023); }

  b = constrain(map(pot, 385, 640, 0, 1023), 0, 1023);
  if(pot > 640) { b = constrain(map(pot, 640, 1023, 1023, 0), 0, 1023); }

  // print that value to the serial interface
  Serial.print(r);
  Serial.print(",");
  Serial.print(g);
  Serial.print(",");
  Serial.print(b);
  Serial.print("\n");

  // wait 1 second and repeat
  delay(1000);

}

Upload this code to an Arduino. It maps a 0-1023 value to three rising/falling patterns for the colors using map() and constrain() as introduced in the advanced LED tutorial.

This is very similar to the python code above, except that it imports serial and reads the RGB string sent by the Arduino, passing it along to the Oak.

import requests
import serial
from time import sleep

ser = serial.Serial("/dev/ttyACM0", 9600)
sleep(2)

device_id = 'device_id_here'
access_token = 'token_here'
 
while True:

    ## read the serial data sent and store as the arguments to send
    args = ser.readline()
    print args

    ## put together the URL for POST
    r = requests.post('https://api.particle.io/v1/devices/%s/set' % device_id, \
                  data={'args': args, 'access_token':access_token})

    ## print the response
    print (r.text)

When we have the appropriate code uploaded to both the Arduino and the Oak, we can read the potentiometer, transmit it to the cloud, and have the Oak update based on it's value! I've commented out the line for printing r.text, so this demonstration will only show the RGB values being translated by the Arduino and sent over serial:

Now you know at least one method of relaying data collected locally to the Oak! While this was done with a computer and Arduino, this could have been done even easier with a Raspberry Pi, which can run python and has input pins. The Pi could read data from a sensor, and then do something interesting with the Oak which is in a separate location.

On the other hand, being able to do this with an Arduino is useful in that you can now essentially give your Arduino network abilities by leveraging python, and the Arduino makes is super easy to read in all sorts of digital and analog devices. In a final project, having a laptop required as one of the components is obviously not practicle… but the python/Arduino combination can let you do a lot of prototyping before you figure out your final design. What's your next project going to be?