smoothieware-website-v1

Smoothie Accessory Protocol Notes

Hardware Protocols

UART:

I2C:

SPI:

Software Protocol

Command Message Structure

  <Virtual Address 8bit><Command Type 8bit><Data Length 1-4byte><Command Data ...><Checksum 8bit>

Reply Message Structure

  <Status 8bit><Data Length 1-4byte><Data 0+byte><Checksum 8bit>

Memory Maps

Virtual Device 0x00 (Module Manager) Memory Map

  0x0000  Magic Number (128bit read only)
   - This identifies the device as a compatible accessory and must always contain the magic value "SMOOTHIEWAREMINI"
  0x0010  Creator ID (128bit read only)
   - This field identifies the device manufacturer, similar to VID in plug and play. Using a 16-byte UUID for these fields allows anyone to generate their own unique numbers with no need for a central tracking system.
  0x0020  Device Type ID (128bit read only)
   - This field uniquely identifies the device type, like the PID in plug and play.
  0x0030  Device Serial (128bit read only)
   - This field holds a device serial that should actually be unique.
  0x0040  *** (196byte)
  0x0100  Upstream UART Config
  0x0200  Upstream SPI Config
  0x0300  Upstream I2C Config

System Memory Map

  - System Memory Maps are 128 bytes.
  - Every virtual device has its own System Memory Map for configuration and basic control.
  - This leaves each virtual device's main memory map free, preventing conflicts with existing memory maps.
  0x00    Module ID (128bit read only)
   - This field contains a unique identifier for the running module. Virtual Device `0x00` (Module Manager) has a Module ID of `0x0000 0000 0000 0000`.
  0x10    Status Flags (32bit read only)
     0b0  starting
     0b1  disabling
     0b2  pausing
     0b3  resuming
     *** 28 bits free
  0x14    State Flags (16bit)
     0b0  disabled
       - When disabled, the device will only process System Command Types `0x00` through `0x1F`. It will continue to run (assuming it's not paused), but will only complete commands that have already been received.
     0b1  paused
       - When paused, the device will 'stop', the meaning of which depends on what the device in question actually does. It will, however, continue to accept all commands as normal (assuming it's enabled).
     *** 14 bits free
     1b0  binary mode
       - If false then 'text mode' is used, which requires any binary commands to be prefixed with a `\0`.
     *** 15 bits free
  0x16    IRQ Flags (16bit)
     0b0  IRQ system enabled
     0b1  config IRQ enabled
     0b2  queue empty IRQ enabled
     0b3  queue full IRQ enabled
     *** 3 bits free
     0b7  module IRQ enabled
     1b0  connect IRQ asserted
     1b1  config IRQ asserted
     1b2  queue empty IRQ asserted
     1b3  queue full IRQ asserted
     *** 3 bits free
     1b7  module IRQ asserted
  0x18    Virtual Address (1byte)
   - Reading this value may be a little pointless, but by writing you will change the address being used. After changing the Virtual Address, the next command sent to the virtual device will need to use the new address. The Virtual Address of Virtual Device `0x00` (Module Manager) cannot be changed.
  0x19    Command Buffers (1byte)
      b0  command bitsize (4bit)
       - This value describes the maximum length command the accessory is capable of receiving in bits. The current plan is for the default to be 5, which means a 32-byte buffer. The value must be from 4 to 28, though this is also limited by available hardware resources like RAM.
      b4  queue bitsize (4bit)
       - This is the size of the command queue in bits. Currently shooting for a default of 4, which would let the queue hold up to 16 commands.
  0x1A    Queue Time Division (2bytes)
      b15 timing (1bit)
       - If 0 then the low 15 bits represent ticks per sync/beat. If 1 then b8-b14 are frames per second, and b0-b7 are ticks per frame.
      b0  sync divisor (15bit)
      b8  timecode frame divisor (7bit)
      b0  timecode tick divisor (8bit)
  0x1C    Queue State (4byte)
   - Holds the number of commands currently in the queue.