BioBoard/Documentation/Arduino protocol

From Noisebridge
Jump to navigation Jump to search

The BioBoard Protocol[edit]

In order for the Arduino, with all its cool sensors connected, to communicate to the outside world, there needs to be an agreement on how that data should look. Otherwise, all that great data would be lost. Hence, the BioBoard Protocol.

An Example[edit]

The best way to explain the details of the protocol is with some examples. If we want to tell the server that the current temperature is 25.5 degrees C, the Arduino sends the following packet:

 @TC:0:25.5$

TC is the tag for "temperature in degrees C". It is a floating point number (i.e. has a decimal point). Besides that, the rest is really just syntactic sugar. Here are some simple rules:

  • All packets begin with @ and end with $ characters.
  • Fields are separated with a : character.
  • After the @ character, is a tag for the type of packet. The tags are typically in all capitals.
  • If the tag indicates a type of probe or sensor, it is followed by a probe number. This is always an integer.

Here is a list of tags that we currently use:

  • TC temperature in degrees C
  • NIR near-infrared transmission (the range is from 0.00 to 1.00, where 1.0 is full transmission)
  • PH pH (the range is from 0.0 [strongest acid] to 14.0 [strongest base])
  • DO dissolved oxygen (the range is from 0.00 to 1.00)

Getting Started[edit]

All protocols need a way to get started. The BioBoard protocol is no different.

For starters, we first output a packet that is different than any of the other packets. You'll notice that we also include a version number.

 !BIOBOARD:0.1

Immediately after the "starter packet" we output the project name. This can be anything, but you shouldn't use any of the reserved characters described above. But, letters, numbers, and spaces are fine.

 @PROJ:TESTLIQUID5$

Ok, we are still not outputting any data packets, because there is one more thing we need to do-- that is, to declare which probes are active.

 @PR:TC:0$
 @PR:NIR:0$
 @PREND$

Here, we have declared two probes, TC probe 0, and NIR probe 0. At the end of the declarations, we output a PREND tag.

Finally, we are ready to output data packets! This is the fun part of the protocol.

 @NIR:0:0.99$
 @TC:0:25.5$
 @TC:0:25.25$
 @TC:0:24.75$
 @TC:0:24.25$
 @TC:0:23.0$

As you can see, these packets seem to indicate that the temperature is dropping. Maybe an ice cube was dropped near the probe? Actually, we just made up the numbers, but it might as well have been an ice cube!

Also, you might have noticed that there are more TC packets than NIR packets. There is no restriction on how often each probe reports its data. In fact, the Arduino sketch, depending on how it is coded, will determine how often each type of data packet is output.

Finally, the BioBoard protocol is line-oriented, meaning that a newline or carriage return is sent after each packet. This makes it easier to view the data or to make up sample data in a simple text editor. Also, the communication speed is 19,200 baud. The Arduino, including older models, can easily handle this speed. Of course, this can be changed, but it would need to be adjusted on the receiving end as well. Remember, a protocol is an agreement between two sides of a communication link!

Arduino Sample Code[edit]

Here are two Arduino sketches that implement the BioBoard Protocol. The first simply reads the temperature probe. The second reads from two probes and outputs data packets with their values.

  • [1] temperature_sensor_NEW-110429a.zip - sketch that uses TC probe only
  • [2] bioboard_all_sensors-110502a.zip - sketch that uses TC and NIR probes