BrickPi Information

mattallen37 · Post by **mattallen37** » 20 Oct 2013, 00:35

This is a list of information about the BrickPi, and how to use it. It will likely be modified and added to in the future.

Terms Explained

"BrickPi Basic Power" vs. "BrickPi Advanced Power"

BrickPi 5V Regulators

BrickPi Power Supply

Using I2C devices on sensor ports 1-4

Using Hardware I2C on sensor port 5

Sensor port 5 is connected to the RPi HW I2C bus available on the GPIO header. On RPi Rev 1 it's /dev/i2c-0 (I2C bus 0), and on Rev 2 it's /dev/i2c-1 (I2C bus 1). The configuration/setup of the resources is handled automatically when the BrickPiSetup() function is called.

The RPi HW I2C bus (sensor port 5) has nothing to do with the microcontrollers of the BrickPi, or the other sensor ports. The entire structure and setup is completely different. The following functions use direct calls to the RPi OS, and the actions take place immediately, and are independant from BrickPiUpdateValues().

You can set the I2C bus speed using BrickPiSetupI2C(SPEED), where SPEED is the speed in bits per second. For example, BrickPiSetupI2C(10000); would set the bus speed to 10000 (10k bps). The speed can be anywhere from 5000 (5k bps) to 1000000 (1m bps). Some I2C devices have minimum and/or maximum rated speeds. Note that the I2C bus electrical charactoristics (pullup resistor strength, physical bus length etc.) will affect the communication performance and speed. 100000 (100k bps) is a pretty standard speed supported by most I2C slaves. The default I2C bus speed is 100000 (100k bps), configured by BrickPiSetup().

You can write to an I2C slave using I2C_WriteArray(ADDR, COUNT, ARRAY), where ADDR is the slave I2C bus address (bits 1-7 of 0-7), COUNT is the number of bytes to write, and ARRAY is the array of bytes to write.

You can read from an I2C slave using I2C_ReadArray(ADDR, COUNT, ARRAY), where ADDR is the slave I2C bus address (bits 1-7 of 0-7), COUNT is the number of bytes to read, and ARRAY is the array to store the incoming bytes.

You can perform a write-read with an I2C slave using I2C_WriteReadArray(ADDR, OUT_COUNT, OUT_ARRAY, IN_COUNT, IN_ARRAY), where ADDR is the slave I2C bus address (bits 1-7 of 0-7), OUT_COUNT is the number of bytes to write, OUT_ARRAY is the array of bytes to write, IN_COUNT is the number of bytes to read, and IN_ARRAY is the array to store the incoming bytes.

UART communication between RPi and microcontrollers

Each of the two microcontrollers (MCUs) handles two sensor ports (1 and 2, or 3 and 4), and two motor ports (A and B, or C and D). In the MCU firmware, the MCU doesn't know which sets of ports it's connected to, so the terms sensor port 1 and 2, and motor port A and B are used (even though they might actually be 3 and 4, and C and D). The RPi takes care of differentiating between the MCUs using a communication address (more on this later).

The RPi and BrickPi microcontrollers (MCUs) use UART to communicate. Because there are two MCUs on the BrickPi, the hardware is designed so that both MCUs get the UART signals from the RPi, and the RPi gets the UART signals from both MCUs.

The UART format is 8N1, at 500k baud. The newer versions of the BrickPi FW start out at 9600 baud, and can be changed.

The UART communication from the RPi to the MCUs implements a simple addressing byte. Each of the two MCUs has a unique address that it listens for. If the MCU recognizes it's address, it will act on the message, otherwise it will discard the message. By default the MCUs use addresses 1 and 2, but anything from 1 - 254 should work (just as long as two MCUs don't have the same address). If the RPi transmits with address 0 (for message types MSG_TYPE_E_STOP, MSG_TYPE_CHANGE_ADDR, and MSG_TYPE_BAUD_SETTINGS), all the MCUs will act on the message, but won't send a reply (for MSG_TYPE_CHANGE_ADDR broadcasted to all MCUs, a touch sensor on sensor port 1 or 3 (corresponding to the MCU to be targeted) must be pressed).

This is what the message format (header and data) looks like for all messages:

RPi to MCUs:

Code: Select all

byte   name         description
0      DEST_ADDR    Destination address for the message, or 0 for BROADCAST.
1      CHECKSUM     Checksum computed across the DEST_ADDR, BYTE_COUNT, and data.
2      BYTE_COUNT   The count of data bytes in the message body, excluding the header.
3-n                 The data

MCU to RPi (no need for address):

Code: Select all

byte   name         description
0      CHECKSUM     Checksum computed across the BYTE_COUNT and data.
1      BYTE_COUNT   The count of data bytes in the message body, excluding the header.
2-n                 The data

On top of the header, the first of the data bytes is a MSG_TYPE byte that specifies what type of message is being sent. At the time of writing this, these are the available message types:

Code: Select all

MSG_TYPE_CHANGE_ADDR      Change the UART address.
MSG_TYPE_SENSOR_TYPE      Change/set the sensor type.
MSG_TYPE_VALUES           Set the motor speed and direction, and return the sensors' and encoders' values.
MSG_TYPE_E_STOP           Float motors immediately
MSG_TYPE_TIMEOUT_SETTINGS Set the timeout
MSG_TYPE_BAUD_SETTINGS    Set the baud rate

Some of the MSG_TYPE types make use of a compressed communication format. If for example there are only 3 significant bits for one value, 4 for another, and 7 for another, the message might be packed (depending on the message type) to use only the first 14 bits of two bytes (wasting 2 bits, instead of using 3 bytes with 10 bits wasted), in order to save communication time. When building a message, this is done with the AddBits function, and when parsing a message, this is taken care of using the GetBits function.

Byte array, specific to message type. RPi to MCU:

MSG_TYPE_CHANGE_ADDR:

Code: Select all

1 byte the new address
  
Reply from MCU:
  1 byte MSG_TYPE_CHANGE_ADDR (just the message type, with no following data)

MSG_TYPE_SENSOR_TYPE:

Code: Select all

two bytes, one for each sensor's SensorType.
for each of the two sensor ports (1 and 2, or 3 and 4):
  if the sensor type is TYPE_SENSOR_I2C or TYPE_SENSOR_I2C_9V:
    8 bits of I2C_Speed
    3 bits of I2C_Devices (0-7, for 1-8 devices on the sensor port's I2C bus)
    for each of the I2C_Devices:
      7 bits of I2C_Addr (bits 0-6 of 1-7, which get's left shifted by one automatically)
      2 bits of SensorSettings (BIT_I2C_MID and BIT_I2C_SAME flags)
      if BIT_I2C_SAME:
        4 bits I2C_Out_Bytes
        4 bits I2C_In_Bytes
        for I2C_Out_Bytes:
          8 bits I2C_Out_Array data

Reply from MCU:
  1 byte MSG_TYPE_SENSOR_TYPE (just the message type, with no following data)

MSG_TYPE_VALUES:

Code: Select all

for each of the two motor ports (A and B, or C and D):
  if 1 bit:
    ((5 bits) + 1) bits encoder offset (left shifted one, with bit 0 being the sign)
  for each of the two motor ports (A and B, or C and D):
    10 bits (8 bits of PWM (bits 2-9), 1 bit dir (bit 1), 1 bit enable (bit 0))      
  for each of the two sensor ports (1 and 2, or 3 and 4):
    if the sensor type is TYPE_SENSOR_I2C or TYPE_SENSOR_I2C_9V:
      for each of the I2C_Devices:
        if not BIT_I2C_SAME:
          4 bits I2C_Out_Bytes
          4 bits I2C_In_Bytes
          for I2C_Out_Bytes:
            8 bits I2C_Out_Array data

Reply from MCU:
  1 byte MSG_TYPE_VALUES
  for each of the two motor ports (A and B, or C and D):
    5 bits how many bits are required for each of the compressed encoder values for each motor port
  for each of the two motor ports (A and B, or C and D):
    n bits of encoder data (bit 0 being sign, and bits 1-n being the value)
  for each of the two sensor ports (1 and 2, or 3 and 4):
    switch SensorType
      TYPE_SENSOR_TOUCH:
        1 bit sensor value
      TYPE_SENSOR_ULTRASONIC_CONT:
      TYPE_SENSOR_ULTRASONIC_SS:
        8 bits sensor value
      TYPE_SENSOR_COLOR_FULL:
        3 bits sensor colorAddBits(1, 0, 3, SEN[port]);
        10 bits blank ADC value
        10 bits red ADC value
        10 bits green ADC value
        10 bits blue ADC value
            case TYPE_SENSOR_I2C:
      TYPE_SENSOR_I2C_9V:
        I2C_Devices bits where each bit represents the success of I2C communication with the corresponding I2C device
        for I2C_Devices:
          if I2C transaction with I2C device was successful:
            for I2C_In_Bytes:
              8 bits I2C_In_Array
      TYPE_SENSOR_RCX_LIGHT:
      TYPE_SENSOR_COLOR_RED:
      TYPE_SENSOR_COLOR_GREEN:
      TYPE_SENSOR_COLOR_BLUE:
      TYPE_SENSOR_COLOR_NONE:
      default:
        10 bits sensor value

MSG_TYPE_E_STOP:

Code: Select all

no additional data
  
Reply from MCU:
  1 byte MSG_TYPE_E_STOP (just the message type, with no following data)

MSG_TYPE_TIMEOUT_SETTINGS:

Code: Select all

4 byte unsigned long (least significant byte first) timeout in ms
  
reply from MCU:
  1 byte MSG_TYPE_TIMEOUT_SETTINGS (just the message type, with no following data)

MSG_TYPE_BAUD_SETTINGS:

Code: Select all

3 byte unsigned long (least significant byte first) baud in bps
  
reply from MCU:
  1 byte MSG_TYPE_BAUD_SETTINGS (just the message type, with no following data)

Mindboards

BrickPi Information

BrickPi Information

Who is online