Overview
The MSB2 and LSB both use the same firmware core with custom modifications to support the sensors and other subsystems specific to each platform. The goals of the firmware are:
- Encapsulate all low level functions in easily accessible commands
- Hides all startup/initialization routines
- Provide a variable sampling schedule (with some constraints) that automatically handles powering off unused sensors
- Provide commands for accessing calibration and other sensor metadata
- Sample and send data via a hi-speed binary uart interface
- Communicates with any embedded platform
- Communicates with any desktop/laptop/handheld/cell phone with a available uart port
State Diagram
The system has two main states, the default wait state and the running state. The other states are used for setting up various components of the system. Once everything is working; however, the user simply enters the running state and begins recording data. In addition to the command states shown here available here several other commands are available (depending upon the hardware) which can be used to manipulate various parts of the system.
System state diagram for communicating with the MSB firmware, the power point version is available
here
Communication protocol
Communication with the MSB Firmware takes place over the first uart on the ATmega, at 921,600 baud, with an option of having flow control. You must only send one byte per timer interrupt! For example, if your INTERRUPT_COUNT is set to 5120 (512 Hz), you must wait at least 1/512th of a second between bytes.
Commands
Commands are six-character sequences where '!' (hex 0x21) indicates the start of a command. The parser is reset by a '!', so if you make a mistake when sending a command, simply resend the command starting with a '!'. Some commands include their arguments as part of their five command bytes.
| Byte 0 |
Byte 1 |
Byte 2 |
Byte 3 |
Byte 4 |
Byte 5
|
| '!' |
0x21 |
Command
|
Note: '!' is a reserved character and may not be used as an argument for any command that includes its arguments in the command bytes.
LED Commands
LED commands are special one-byte commands that turns the LEDs on and off. Two LED command formats exist: one to adjust the individual LEDs, and one to adjust both the individual LEDs and the tri-color LED. In both formats, a 0 bit for an LED turns it on, and a 1 bit turns it off.
Individual LED command format
| Bit 7 |
Bit 6 |
Bit 5 |
Bit 4 |
Bit 3 |
Bit 2 |
Bit 1 |
Bit 0
|
| 0 |
0 |
0 |
0 |
Red |
Green |
Blue |
1
|
Individual and Tricolor LED command format
| Bit 7 |
Bit 6 |
Bit 5 |
Bit 4 |
Bit 3 |
Bit 2 |
Bit 1 |
Bit 0
|
| 1 |
Tri-color Blue |
Tri-color Green |
Tri-color Red |
Red |
Green |
Blue |
1
|
Packet format (from the MSB Firmware)
All MSB firmware responses will be sent back as packets that begin with 2 characters '#' followed by '|', then an identifier byte describing what the packet is and how it should be interpreted.
| Byte 0 |
Byte 1 |
Byte 2 |
... |
Byte N
|
| '#' |
0x23 |
'|' |
0x7C |
ID |
Payload |
Checksum
|
The checksum is calculated by adding up all bytes 2 through N - 1, and taking the lower 8 bits of the result.
Packet IDs
Example Communication Sequence
Here's an example of what a host computer would send to query the state of the LED and what it would receive from the MSB:
Host sends: '!query' + 0x10 [query command + 0x10 to indicate a LED query]
| Byte 0 |
Byte 1 |
Byte 2 |
Byte 3 |
Byte 4 |
Byte 5 |
Byte 6
|
| '!' |
0x21 |
'q' |
0x71 |
'u' |
0x75 |
'e' |
0x65 |
'r' |
0x72 |
'y' |
0x79 |
|
0x10
|
MSB Firmware responds with: ['#|' start header + 0x10 to indicate a LED packet and 0x00 the current state of the LEDs
| Byte 0 |
Byte 1 |
Byte 2 |
Byte 3
|
| '#' |
0x23 |
'|' |
0x7C |
|
0x10 |
0 |
0x00
|
Available Commands
Start Command
This command begins sampling of the sensors and outputting the readings. May only be executed in the WAIT state.
Host sends: '!start'
| Byte 0 |
Byte 1 |
Byte 2 |
Byte 3 |
Byte 4 |
Byte 5
|
| '!' |
0x21 |
's' |
0x73 |
't' |
0x74 |
'a' |
0x61 |
'r' |
0x72 |
't' |
0x74
|
Cease Command
This command stops sampling of the sensors. May only be executed in the RUNNING state.
Host sends: '!cease'
| Byte 0 |
Byte 1 |
Byte 2 |
Byte 3 |
Byte 4 |
Byte 5
|
| '!' |
0x21 |
'c' |
0x63 |
'e' |
0x65 |
'a' |
0x61 |
's' |
0x73 |
'e' |
0x65
|
Reset Command
This command reinitializes the sensor board. May only be executed in the WAIT state.
Host sends: '!reset'
| Byte 0 |
Byte 1 |
Byte 2 |
Byte 3 |
Byte 4 |
Byte 5
|
| '!' |
0x21 |
'r' |
0x72 |
'e' |
0x65 |
's' |
0x73 |
'e' |
0x65 |
't' |
0x74
|
Alter Schedule Command
This command alters the sensor sampling schedule. May only be executed in the WAIT state.
Host sends: '!alter' SCHED_DATA
| Byte 0 |
Byte 1 |
Byte 2 |
Byte 3 |
Byte 4 |
Byte 5
|
Byte 6 - 23
|
| '!' |
0x21 |
'a' |
0x61 |
'l' |
0x6c |
't' |
0x74 |
'e' |
0x65 |
'r' |
0x72 |
Schedule Data
|
Data Returned
The MSB will verify that it can meet the desired schedule, and if not, will adjust it accordingly. In either case, the effective schedule will be returned over the serial port in the same format, except with "!alter" replaced with the MSB response bytes, with ID = 0x40.
Query Command
This command returns various information about the state of the MSB. May only be executed in the WAIT state.
Host sends: '!query' QUERY_ID
| Byte 0 |
Byte 1 |
Byte 2 |
Byte 3 |
Byte 4 |
Byte 5 |
Byte 6
|
| '!' |
0x21 |
'q' |
0x71 |
'u' |
0x75 |
'e' |
0x65 |
'r' |
0x72 |
'y' |
0x79 |
Query ID
|
Query Types
| ID |
Type
|
| 0x40 |
Current Schedule
|
| 0x20 |
Calibration Information
|
| 0x10 |
LEDs State
|
| 0x02 |
RTC Registers
|
USB Enable Command
This command enables or disables the USB/Digital Compass power. May be executed in either the RUNNING or WAIT states.
Host sends: '!usb-0' or '!usb-1'
| Byte 0 |
Byte 1 |
Byte 2 |
Byte 3 |
Byte 4 |
Byte 5
|
| '!' |
0x21 |
'u' |
0x75 |
's' |
0x73 |
'b' |
0x62 |
'-' |
0x2d |
USB status ('0' or '1')
|
GPS Enable Command
This command sets the state of the GPS Enable signal (Atmel_PA7). May be executed in either the RUNNING or WAIT states.
Host sends: '!gps-0' or '!gps-1'
| Byte 0 |
Byte 1 |
Byte 2 |
Byte 3 |
Byte 4 |
Byte 5
|
| '!' |
0x21 |
'g' |
0x67 |
'p' |
0x70 |
's' |
0x73 |
'-' |
0x2d |
GPS enable ('0' or '1')
|
Gain Command
This command temporarily adjusts the gain while the sensors are being sampled. May only be executed in the RUNNING state.
Host sends: '!gain' GAIN_VALUE
| Byte 0 |
Byte 1 |
Byte 2 |
Byte 3 |
Byte 4 |
Byte 5
|
| '!' |
0x21 |
'g' |
0x67 |
'a' |
0x61 |
'i' |
0x69 |
'n' |
0x6e |
Gain (0x00 to 0xFF)
|
Note: Since '!' is a reserved character, a gain value of 0x21 cannot be set with this command.
Write Command
This writes the current schedule to the EEPROM to be used as the default schedule. May only be executed in the WAIT state.
Host sends: '!write'
| Byte 0 |
Byte 1 |
Byte 2 |
Byte 3 |
Byte 4 |
Byte 5
|
| '!' |
0x21 |
'w' |
0x77 |
'r' |
0x72 |
'i' |
0x69 |
't' |
0x74 |
'e' |
0x65
|
Clock Command
This writes sets the first seven bytes of the RTC registers. May only be executed in the WAIT state. More information on the RTC's registers is available in this datasheet.
Host sends: '!clock'
| Byte 0 |
Byte 1 |
Byte 2 |
Byte 3 |
Byte 4 |
Byte 5 |
Byte 6 |
Byte 7 |
Byte 8 |
Byte 9 |
Byte 10 |
Byte 11 |
Byte 12
|
| '!' |
0x21 |
'c' |
0x63 |
'l' |
0x6c |
'o' |
0x6f |
'c' |
0x63 |
'k' |
0x6b |
RTC Reg 0 |
RTC Reg 1 |
RTC Reg 2 |
RTC Reg 3 |
RTC Reg 4 |
RTC Reg 5 |
RTC Reg 6
|
RTCal Command
This writes sets the RTC's calibration register. May only be executed in the WAIT state. More information on the RTC's registers is available in this datasheet.
Host sends: '!rtcal'
| Byte 0 |
Byte 1 |
Byte 2 |
Byte 3 |
Byte 4 |
Byte 5 |
Byte 6
|
| '!' |
0x21 |
'r' |
0x72 |
't' |
0x74 |
'c' |
0x63 |
'a' |
0x61 |
'l' |
0x6c |
RTC Reg 7
|
Data Format
Schedule Format
| Byte 0
|
Byte 1 |
Byte 2 |
Byte 3 |
Byte 4
|
Byte 5 |
Byte 6 |
Byte 7 |
Byte 8 |
Byte 9
|
| Interrupts Per 10 Secs |
Mic Hz |
Accelerometer Hz * 10 |
Ambient Light Hz * 10 |
Barometer Hz * 10
|
| Low-order |
High-order |
Low-Order |
High-Order |
Low-Order |
High-Order |
Low-Order |
High-Order |
Low-Order |
High-Order
|
| Byte 10 |
Byte 11 |
Byte 12 |
Byte 13 |
Byte 14 |
Byte 15 |
Byte 16 |
Byte 17
|
| Compass Hz * 10 |
DALS Hz * 10 |
Humidity Hz * 10 |
Power Control |
Mic Gain
|
| Low-order |
High-order |
Low-Order |
High-Order |
Low-Order |
High-Order
|
Power Control Bits
Certain sensors can be powered down in between samples. To enable this, set the appropriate bits in the power control byte. Note that due to the amount of time required to power up and down the sensors, the maximum sampling rate will be decreased for these sensors.
| Bit 7 |
Bit 6 |
Bit 5 |
Bit 4 |
Bit 3 |
Bit 2 |
Bit 1 |
Bit 0
|
| 0 |
0 |
0 |
0 |
0 |
Accel |
Compass |
DALS
|
Microphone Gain
This byte ranges from 0 to 255. 0 represents minimal gain, while 255 represents maximal gain. The gain may also be adjusted during sampling with the !gain command.
Microphone Data Packet
| Byte 0 |
Byte 1 |
Byte 2 |
Byte 3 |
Byte 4 ... N
|
| Number of Samples |
Time Counter |
Interrupt Counter |
Samples
|
| Low-order |
High-order |
Low-Order |
High-Order
|
Samples are all 16-bit unsigned integers, in little-endian order.
Error Packets
Error Codes
| Error Code |
Description
|
| 'F' |
Incorrect Firmware for hardware
|
| 'I' |
Timeslice overrun
|
| 'B' |
Microphone buffer overflow
|
| 'S' |
Sensor readings buffer overflow
|
| 'M' |
Microphone buffer overflow
|
Calibration Information Packet
| Byte 0
|
Byte 1 |
Byte 2 |
Byte 3 |
Byte 4
|
Byte 5 |
Byte 6 |
Byte 7 |
Byte 8 |
Byte 9
|
| Board Serial Number |
Hardware Version |
Major Software Version |
Minor Software Version |
Barometer Calibration Word 1 |
Barometer Calibration Word 2
|
| Low-order |
High-order |
Low-Order |
High-Order |
Low-Order |
High-Order |
Low-Order |
High-Order
|
| Byte 10
|
Byte 11 |
Byte 12 |
Byte 13 |
Byte 14
|
| Barometer Calibration Word 3 |
Barometer Calibration Word 4 |
Mic Gain
|
| Low-order |
High-order |
Low-Order |
High-Order
|
Hardware Version Codes
| Error Code |
Description
|
| 0x00 |
MSB for iMote1
|
| 0x01 |
MSB for iMote2
|
| 0x02 |
MSB2 for iMote2
|
| 0x03 |
MSB2 Rev C for iMote2
|
| 0x10 |
LSB
|
Sensor Packets
| Byte 0
|
Byte 1 |
Byte 2 |
Byte 3 |
Byte 4
|
Byte 5 |
Byte 6 |
Byte 7 |
Byte 8 |
Byte 9
|
| Sensors Bit Mask |
Time Counter |
Interrupt Counter |
Accelerometer X Axis |
Accelerometer Y Axis |
Accelerometer Z Axis
|
| Low-order |
High-order |
Low-Order |
High-Order |
Low-Order |
High-Order |
Low-Order |
High-Order
|
| Byte 10
|
Byte 11 |
Byte 12 |
Byte 13 |
Byte 14
|
Byte 15 |
Byte 16 |
Byte 17 |
Byte 18 |
Byte 19
|
| Ambient Light Sensor Gain |
Ambient Light Sensor Reading |
Barometer Temperature |
Barometer Pressure |
Compass |
DALS Visible Light
|
| Low-order |
High-order |
Low-Order |
High-Order |
Low-Order |
High-Order |
Low-Order |
High-Order
|
| Byte 20
|
Byte 21 |
Byte 22 |
Byte 23 |
Byte 24
|
| DALS Infrared Light |
Humidity Temperature |
Humidity
|
| Low-order |
High-order |
Low-Order |
High-Order
|
Sensor Bit Mask
| Error Code |
Description
|
| 0x01 |
Accelerometer
|
| 0x02 |
DALS Visible Light
|
| 0x04 |
DALS Infrared Light
|
| 0x08 |
Compass
|
| 0x10 |
Barometer Pressure
|
| 0x20 |
Barometer Temperature
|
| 0x40 |
Humidity
|
| 0x80 |
Humidity Temperature
|
When the least-significant bit of the Packet ID is set, the ambient light data is also available. Only the bytes for the sensors present in the sensor bit mask are sent. For example, if there's only an accelerometer and DALS Visible light reading, only bytes 0-9 and 19 will be sent. All sensor readings are directly taken from the sensors. Consult each sensor's datasheet for interpretation.
