Difference between revisions of "I²C API"

From veeOp Wiki
Jump to: navigation, search
(Created page with " The I²C API on the microcontroller is a rather simple little set of commands that rides on I²C. For more information about [http://en.wikipedia.org/wiki/I%C2%B2C I²C we di...")
 

Latest revision as of 13:23, 11 October 2013

The I²C API on the microcontroller is a rather simple little set of commands that rides on I²C. For more information about I²C we direct you to Wikipedia.

In practice, this is also abstracted by the veeOP REST API, which resides on the Raspberry Pi. The REST API is much more verbose, and provides more flexibility in handling the day-to-day tasks with your veeOP. But, should you see an opportunity to extend it's communication -- it's a simple system. Don't let all the bits and bytes confuse you here, when it comes down to it it's this simple:

  1. Raspberry Pi says "Hi, microcontroller, I want you to do something."
    1. ...And sends it 4 bytes to tell it to do so.
  2. Microcontroller says "Sure! I did what you want, and here's some info about it."
    1. ...And it sends 4-bytes back to the Raspberry Pi.

The veeOP uses the Raspberry Pi as the I²C master, with the arduino-compatible being the slave, at address 4 (0x04) by default (this is configurable in the library.)

Contents

Download the code!

If you're using one of the downloadable pre-customized distros, you can look in: 

/home/pi/arduino-vop/src/

For the source code. But, if you really want to dig in -- download the code from google code.

It's as simple as placing the vOP folder into your libraries folder in your Arduino's default install directory, to compile it. Check out the provided example sketch as it will guide you into extending the functionality. You can use the provided example sketch to keep the veeOP functionality intact, but! Use the microcontroller for other purposes, and it's extend it's functionality.

How Commands are transmitted

Commands are sent to the veeOP arduino-compatible with a 4-byte tuple. It looks like so:

(C,P_1,P_2,C_e)

Where each element is a single byte, representing:

\begin{align} C & = \text{Command} \\ P_1 & = \text{First Parameter} \\ P_2 & = \text{Second Parameter} \\ C_e & = \text{Command Ending (0x0A)} \\ \end{align}


  • C (command) is any (known) value other than 10 (0x0A, in hex.) and originally assigned all higher 10.
  • P_1 & P_2 are sometimes treated as individual integer values each, or together as a 16 bit integer, depending on context.
  • C_e Command ending allows the microcontroller know when a command is incomplete, or too many bytes are sent.


Why's it end in 10? It's the "end of line" ASCII character, check it out asciitable.com.

How responses are received

When the microcontroller recieves the proper 4 bytes for the command, it responds in turn with a response of 4 bytes.

(E,C_r,R_1,R_2)

Where each element is a single byte, representing:

\begin{align} E & = \text{Error Code} \\ C_r & = \text{Command return} \\ R_1 & = \text{First return byte} \\ R_2 & = \text{Second return byte} \\ \end{align}


  • E errors of a value of 0 denotes an error-free response, any non-zero value is defined in a table below.
  • C_r is a redundant byte that represents C from the sent command. This is used for error handling on the raspberry pi.
  • R_1 & R_2 are the resulting responses from the command. Treated as two bytes, or a 16-bit unsigned integer depending on the context of the command.


Commands

In this chart, we show each available command, and it's return type. The example commands and responses are given showing each 4-byte command and response, in decimal.

Command Description Value P_1 P_2 Returns Example Command (Decimal) Example Response (decimal) Example Description
Check Ignition State 11 - - Boolean (11,0,0,10) (0,11,0,1) Response showing the ignition is on. An R_2 value of 1 denotes the ignition is on, where a value of 0 denotes it being off.
Last time ignition changed (seconds ago) 12 - - 16-bit Integer (12,0,0,10) (0,12,1,2) Responds showing us the ignition last changed it's state 258 seconds ago. See 16-bit integer note, below.
Last time ignition changed (minutes ago) 13 - - 16-bit Integer (13,0,0,10) (0,13,0,90) Responds showing us the ignition last changed it's state 90 minutes ago
Pat the watchdog 15 - - - (15,0,0,10) (0,15,0,0) Responds simply stating it pat the watchdog without an error.
Echo bytes sent 14 Byte Byte 2 Bytes (14,1,2,10) (0,14,1,2) Simply echos the sent bytes back. Returns P_1 as R_1 and returns P_2 as R_2. Mainly useful as

16-bit Integer Example

Using the "Last time ignition changed (seconds ago)" command example from above.

Note that R_1 and R_2 represent a 16 bit integer.In the response (1,2) could be represented as bytes in hex as \text{(0x01,0x02)}, which will convert as a little endian into a decimal value of \text{0x102 hex = 258 dec}

Error Codes

E value Code Constant Description
1 ERR_BUFFER_OVERFLOW Too many bytes received before C_e
2 ERR_COMMAND_UNKNOWN Command is unknown.
3 ERR_COMMAND_INCOMPLETE Request for data from master received before C_e sent.
Retrieved from "http://wiki.mapletaps.dougbtv.com/index.php?title=I²C_API&oldid=59"