MSB2 Firmware
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.
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
| ID | Type |
|---|---|
| 0x00 | Sensor Packet |
| 0x01 | Sensor Packet |
| 0x02 | RTC Packet |
| 0x04 | Error Packet |
| 0x08 | Microphone Packet |
| 0x10 | LEDs Packet |
| 0x20 | Calibration Packet |
| 0x40 | Schedule Packet |
| 0x80 | Power Packet |
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.
