MSB2 Firmware

From University of Washington - Ubicomp Research Page
Jump to navigationJump to search

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

    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.

Microphone Data Packet

    Byte 0 Byte 1 Byte 2 Byte 3 Byte 4 ... N
    Number of Readings 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

    Byte 0
    Error Code

    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
Retrieved from "https://ubi.cs.washington.edu/wiki/index.php?title=MSB2_Firmware&oldid=1849"