daily pastebin goal
45%
SHARE
TWEET

Communication Protocol SpiNNaker <-> TUM Board 28-7-14

a guest Sep 22nd, 2014 76 Never
Not a member of Pastebin yet? Sign Up, it unlocks many cool features!
  1.  
  2. ***************************************************************************************************************************
  3.   Communication Protocol SpiNNaker <-> generic external Hardware connected to TUM IO Board                        28.7.2014
  4. ***************************************************************************************************************************
  5. General remarks about the IO Board:
  6.                 all UART interfaces in this document are "logic" UARTs numbered from 0 to 4 counter-clockwise on the physical board
  7.                         all UARTs by default are configured to 4mbps, 8N1, full handshaking RTS/CTS
  8.                         UARTs 1+2 can support 8mbps for specific projects' demands
  9.                                          ,-------------------------.    top view
  10.                                          |    UART4*       *UART3  |    (asterisks indicate pin1 of port)
  11.                                          |   (debug)               |
  12.                     ,--------------------’                         |
  13.                     | *                                            |
  14.                     | S L      .------.       .------.             |
  15.                     | p i      | CPLD |       |  uC  |     *UART2  |
  16.                     | i n      `------’       `------’             |
  17.                     | n k                                          |
  18.                     `--------------------.                         |
  19.                                          |                         |
  20.                                          |    *UART0       *UART1  |
  21.                                          `-------------------------’
  22.                 UART port 4 (last port counterclockwise) is debug port; can be connected to PC (FTDI adapter) to monitor operation
  23.                                                 can be used to stream out (visualize) spiNNaker data for debug
  24.                                                 can generate arbitrary "spinnaker packets" to go into the system
  25.                 UART ports 0..3 are available for external hardware;
  26.                                                 up to 4 retinas can be connected to any one (or multiple) of UART ports 0..3
  27.                                                 specific hardware (e.g. SpomniBot, BallBalancer) requires the use of a particular UART port
  28. ***************************************************************************************************************************
  29. ***************************************************************************************************************************
  30. - SpiNNaker -> external Hardware
  31. ***************************************************************************************************************************
  32.    
  33.    The SpiNNaker IO board (currently) only reacts to MultiCast (MC) packets.
  34.    
  35.    Every MC packet received by the IO board (from SpiNNaker) is "valid" - i.e. the board interprets every incoming packet.
  36.    Key top 21 bits are ignored (sender address according to SpiNNaker notation: 8bit x, 8bit y, 5bit coreID)
  37.    
  38.    Key bottom 11 bits "iiiiiiifddd":
  39.                                 7 bits for command id (0-127), 1 bit for payload-format (0-1), 3 bits for dimension (0-7)
  40.         the (optional) payload contains an additional value:
  41.                 format == 0 --> payload 32bit (signed) int
  42.                 format == 1 --> payload for replies(!) encoded in S16.15
  43.                                         - to convert to integer: (value*maximum_value)>>15
  44.                                         - to convert to boolean: (value & 0xA000)
  45.       id=127: Board Configuration
  46.                 dim=0: payload top 21 bits: set new master ID for package transmission IO-Board --> SpiNNaker
  47.                                 default master key: ((254<<24) | (255<<16) | (248<<8))  =  0xFEFFF800
  48.                                 (overwrites possibly set individual retina keys!)
  49.                 dim=1: configure board hardware for a particular project
  50.                                         (such as baud rates on UART ports, enable/disable handshaking, use I2C instead of UART,
  51.                               interpret received data correctly, ...)
  52.                                 PL=0: reset to default (all ports at 4mbps, full handshaking active)
  53.                                 PL=1: PushBot project (all ports at 4mbps, full handshaking active)
  54.                                 PL=2: SpomniBot project (robot at UART0, eDVS at UART1..3; full handshaking active)
  55.                                 PL=3: BallBalancer - lower baud rates for UART0 & UART1, no RTS/CTS
  56.                                 PL=4: Myorobotics project - UART2 configured as CAN controller (1MBit, requires additional hardware)
  57.                                 PL=5..: open for future projects
  58. ***************************************************************************************************************************
  59. ***************************************************************************************************************************
  60.   Project specific keys:
  61. ***************************************************************************************************************************
  62. ***************************************************************************************************************************
  63. ***************************************************************************************************************************
  64.   - eDVS4337 (retina)  id 0..31 is for retina
  65.                 id bits 2..0 (7..0) encode function
  66.                 id bits 4..3 (+24/+16/+8/+0) encode retina ID (which UART port on interface board); up to 4 retinas
  67. ***************************************************************************************************************************
  68.         id=0: Retina eDVS4337 Event Streaming and Reset
  69.             dim=0: disable retina event streaming ("E-")
  70.             dim=1: enable retina event streaming ("E+"), payload specifies data format
  71.                   PL bits 31..29: timestamp:    0: no timestamp
  72.                                                 1: delta-timestamps from sensor; (global) absolute 4 bytes timestamp (in us) provided in packet payload
  73.                                                 2: 2 bytes time-stamp 0..65536us == 65ms - timestamp provided in packet payload
  74.                                                 3: 3 bytes time-stamp 0..16777216us == 16.7s - timestamp provided in packet payload
  75.                                                 4: 4 bytes time-stamp 0..4294967296us == 71 minutes - timestamp provided in packet payload
  76.                                                 5..7: unused
  77.                                                                 (note that activating timestamps enforces event address encoding in keys, see PL bit 28..26 below)
  78.                   PL bits 28..26: event-encoding in payload vs. event-encoding in key (with possible downsampling):
  79.                                                 0: all events transmitted as payload with fixed retina key (use “no timestamp” mode in bits 31..29)
  80.                                                 1: events encoded in lower 15 bits (1p +7x +7y) of key
  81.                                                2: events encoded in lower 13 bits (1p +6x +6y) of key (downsampling:2 -> 64x64 pixel)
  82.                                                 3: events encoded in lower 11 bits (1p +5x +5y) of key (downsampling:4 -> 32x32 pixel)
  83.                                                 4: events encoded in lower  9 bits (1p +4x +4y) of key (downsampling:8 -> 16x16 pixel)
  84.                                                 5..7: unused
  85.             dim=2: payload specifies retina events "sending key" (default is the IO board's key + "retina offset" 0..3)
  86.                           note: this key is only for events, not for sensor data!
  87.             dim=3: payload set internal timer/counter for timestamps (on eDVS and on interface board); without payload set to 0
  88.             dim=4: handle master/slave time synchronization
  89.                   PL = 0: use internal counter, no external synchronization (default)
  90.                   PL = 1: set slave (reset internal timer, connect to external source)
  91.                   PL = 2: set master, clock not started
  92.                   PL = 4: set master, clock active
  93.             dim=5: set Bias values
  94.                   PL bits 31..28: bias ID (0..11)
  95.                   PL bits 23..0:  bias Value (0..16777215)
  96.             dim=6: unused
  97.             dim=7: Reset eDVS4337 retina
  98.       id=1: Request on-board sensor data: https://wiki.lsr.ei.tum.de/nst/documentation/edvs-4337
  99.             dim=0: sensor reporting off (bitfield 31..0, no payload -> all sensors off)
  100.             dim=1: poll multiple sensors once (bitfield 31..0 request multiple sensors simultaneously)
  101.             dim=2: poll individual sensor continuously (specify separately for each sensor)
  102.                         payload bits 31..27: sensor ID (31..0)
  103.                         payload bits 26..0: sensor polling interval (time in ms)
  104.                    the "f" (format) flag allows reply in “binary/decimal” (0) or “S16.15” (1)
  105.       id=2: PWM Motor Output
  106.             dim=0: payload 0/1: disable/enable motor driver
  107.             dim=1: payload = PWM total period duration (in microseconds)
  108.             dim=4: payload = PWM signal for motor 0 (raw motor output, permanent)
  109.             dim=5: payload = PWM signal for motor 1 (raw motor output, permanent)
  110.             dim=6: payload = PWM signal for motor 0 (raw motor output, leaking towards zero)
  111.             dim=7: payload = PWM signal for motor 1 (raw motor output, leaking towards zero)
  112.       id=3: PWM pin Output Duration
  113.             dim=0: payload = timer A total period (in microseconds)
  114.             dim=2: payload = timer B total period (in microseconds)
  115.             dim=4: payload = timer C total period (in microseconds)
  116.       id=4: PWM pin output ratio
  117.             dim=0: payload = timer A, channel 0 active period (in microseconds)
  118.             dim=1: payload = timer A, channel 1 active period (in microseconds)
  119.             dim=2: payload = timer B, channel 0 active period (in microseconds)
  120.             dim=3: payload = timer B, channel 1 active period (in microseconds)
  121.             dim=4: payload = timer C, channel 0 active period (in microseconds)
  122.             dim=5: payload = timer C, channel 1 active period (in microseconds)
  123.       id=5: Digital IO Signals:
  124.             dim=0: query state of IO lines (will trigger a reply, documented below)
  125.             dim=1: set output pattern to payload (6 bits)
  126.             dim=2: add payload (logic or(PL)) to current output
  127.             dim=3: remove payload (logic and(not(PL))) from current output
  128.             dim=4: set payload pins to high impedance (6 bits)
  129.       id=6-7:  unused
  130.       retina id-offset +0 / +8 / +16 / +24:    select UART 0..3 port for retina
  131. ***************************************************************************************************************************
  132.   - PushBot connect to UART0/1/2/3
  133.    The PushBot is controlled by a retina, so id=4..5 are from the retina above, id=32..39 are specific to the robot
  134. ***************************************************************************************************************************
  135.       id=4/12/20/28: Laser/Speaker/LED
  136.             dim=0: total period for laser (in microseconds)                                (part of the eDVS4337 key-space above)
  137.             dim=2: total period for speaker (in microseconds)
  138.             dim=4: total period for top-LED (in microseconds)
  139.       id=5/13/21/29: Laser/Speaker/LED
  140.             dim=0: Laser active time (in microseconds)                                (part of the eDVS4337 key-space above)
  141.             dim=2: Speaker active time (in microseconds)           (typically 1/2 value of id4:dim2 to set 50% duty cycle)
  142.             dim=4: LED back active time (in microseconds)
  143.             dim=5: LED front active time (in microseconds)
  144.       id=32/33/34/35: Track (Motor) Velocity Control:
  145.             dim=0: payload = signal for motor 0 (desired velocity, permanent)
  146.             dim=1: payload = signal for motor 1 (desired velocity, permanent)
  147.             dim=2: payload = signal for motor 0 (desired velocity leaking towards zero)
  148.             dim=3: payload = signal for motor 1 (desired velocity leaking towards zero)
  149.       id=36: Speaker
  150.             dimension bit 0 -> select tone or melody (0=beep; 1=melody)
  151.             dimension bit 2..1 -> select robot/UART port 0..3
  152.                    payload: for tone: specify frequency in Hertz
  153.                    payload: for melody: select melody
  154.       id=37: LED/Laser (at 50% duty cycle)
  155.             dimension bit 0 -> select LED or laser (0=led; 1=laser)
  156.             dimension bit 2..1 -> select robot/UART port 0..3
  157.                    payload: specify frequency in milli-Hertz
  158.       id=38..39:  unused
  159. ***************************************************************************************************************************
  160.   - SpomniBot connect to UART0 (in fact any Munich OmniWheel robot)
  161.     id 40..47 are specific for OmniBot
  162. ***************************************************************************************************************************
  163.       id=40: PWM (direct) motor wheel output
  164.             dim=0..2:  payload = PWM signal for motor 0..2 (raw motor output, permanent)
  165.             dim=4..6:  payload = PWM signal for motor 0..2 (raw motor output, leaking towards zero)
  166.             dim=7:     payload = PWM total period duration (in microseconds)
  167.       id=41: Motor Wheel Velocity Control:
  168.             dim=0..2: payload = signal for motor 0..2 (desired velocity, permanent)
  169.             dim=4..6: payload = signal for motor 0..2 (desired velocity leaking towards zero)
  170.             dim=7: emergency stop (all three wheels)
  171.       id=42: Motor Abstract Driving Commands (desired velocities in robots coordinate frame)
  172.             dim=0: payload = desired velocity in frontal direction, forward is positive
  173.             dim=1: payload = desired velocity in lateral (sideways) direction, right is positive
  174.             dim=2: payload = desired velocity in rotation (counter-clockwise is positive)
  175.             dim=4..6: same with leaking velocities towards zero
  176.             dim=7: emergency stop (all three wheels)
  177.       id=43: Robot Control and Beeper
  178.             (dim=0: payload==0 -> enable direct motor mode (id=40)                OUTDATED, the robot changes automatically)
  179.             (       payload!=0 -> enable velocity control mode (id=41/42), default active     OUTDATED)
  180.             dim=6: single beep
  181.             dim=7: double beep (that's all the robot can do...)
  182.       id=44: Request on-board Sensor Data:
  183.             dim=0: sensors reporting off
  184.             dim=1: poll sensors once (payload format below)
  185.             dim=2: poll sensor continuously (payload format below, only bits 0..7 supported)
  186.                     payload = bit pattern to activate sensors (bits 7..0), according to specs on web page:
  187.                         https://wiki.lsr.ei.tum.de/nst/documentation/omnirob
  188.                     the "f" (format) flag indicates if the reply should be sent in binary/decimal or S16.15
  189.             dim=3: reporting frequency in Hz, default 25Hz (robot mainloop frequency 125Hz; only integer-fractions available)
  190.       id=45..47:  unused
  191. ***************************************************************************************************************************
  192.   - BallBalancer (Motors connected to UART0 and UART1)
  193.     id 48..51 are specific for Ball Balancer
  194. ***************************************************************************************************************************
  195.       id=48: Set Servo Motor Position
  196.             dim=0: payload angle x (parallel to left side when looking "diagonal" into balancer)
  197.             dim=1: payload angle y (parallel to right side when looking "diagonal" into balancer)
  198.             dim=7: turn off motors (free plate to allow "hand motion")
  199.       id=49: Request/Read Sensory Data (here we need some explanation about the board's reply)
  200.             dim=0: sensors reporting off
  201.             dim=1: poll sensors once (payload format below)
  202.             dim=2: poll sensor continuously (payload format below)
  203.                     payload = bit pattern to activate sensors
  204.                       bit(0): angle X+Y
  205.                       bit(1): velocity X+Y
  206.                       bit(2): current X+Y
  207.             dim=3: reporting period in ms, default 1000ms (1Hz)
  208.       id=50..51:  unused
  209. ***************************************************************************************************************************
  210.   - LaserMirror (connected to UART0)
  211.     id 52..55 are specific for LaserMirror
  212. ***************************************************************************************************************************
  213.       id=52: Set Pan/Tilt Angle for Laser Mirror
  214.             dim=0: payload angle x (horizontal)
  215.             dim=1: payload angle y (vertical)
  216.             dim=2: payload velocity x (horizontal)
  217.             dim=3: payload velocity y (vertical)
  218.             dim=4: laser power (payload: on/off)
  219.       id=53..56:  unused
  220. ***************************************************************************************************************************
  221. - Myorobotics project (using additional CAN transceiver on UART2)
  222.     id 56..63 are specific for Myorobotics
  223. Register and use up to 8 different motors, 8 different motor monitors and 8 different joint sensors in individual
  224. tables for each type. Register each motor and its corresponding motor monitor to the same single index (use id=56).
  225. Register each agonistic and its corresponding antagonistic muscle to consecutive indices, which allows quasi-simultaneous
  226. control with a single command (id=58).
  227. ***************************************************************************************************************************
  228.       id=56: Register Motor and Corresponding Monitor
  229.             dim=0..7: specifies index at which to register the motor/monitor pair
  230.                       payload: CAN ID of monitor << 16  (bits 31..16) | CAN ID of motor (bits 15..0)
  231.       id=57: Set Motor PWM signal
  232.             dim=0..7: specifies index of the registered target motor
  233.                       payload: PWM signal (range -4000..4000), int32
  234.       id=58: Simultaneously Set Motor PWM signals for 2 Motors at (<dim>) and ((<dim>+1)%8)
  235.             dim=0..7: specifies index of the first registered target motor
  236.                       payload: (int16 PWM value1 << 16) | (int16 PWM value2)     (range -4000..4000)
  237.                                value1 (high bytes) is sent to motor #<dim>
  238.                                value2 (low bytes)  is sent to motor #(<dim>+1)
  239.       id=59: Set/Request Motor Monitor Data Streams (continuous, int32)
  240.             dim=0..7: specifies the index of the registered monitor
  241.                       payload: bit pattern to activate sensor streams
  242.                                bit 3..0: displacement (+8), current (+4), encoder Position (+2), omega (+1)
  243.  
  244.       id=60: Register Joint (Angle) Sensor and Request Continuous Data Stream (int32)
  245.             dim=0..7: specifies index at which to register the sensor
  246.                       payload: CAN ID of the sensor (set to 0 to deregister/mute this stream)
  247.       id=61..63 currently not used
  248. ***************************************************************************************************************************
  249.   - other (future) hardware
  250.         id ..126 are free
  251. ***************************************************************************************************************************
  252.   to come
  253. ***************************************************************************************************************************
  254. ***************************************************************************************************************************
  255. - external Hardware -> SpiNNaker
  256. ***************************************************************************************************************************
  257. The IOBoard does not "by itself" send packets; it only generates replies after queries.
  258. The IOBoard uses the "Master-ID" for the top 21 bits of key (possibly different for retinas); set with key id=127
  259. default master key = 0xFEFFF800
  260. The key space for the 11 lower bits (10:0) needs to be re-designed (differs from sending keys),
  261. as we need to represent a large number of individual responses for some commands (does not fit within dim space),
  262. but for most keys we need no reply at all.
  263. The payload format is specified by the earlier "request" command; will be memorized for an individual id/dimension
  264. ***************************************************************************************************************************
  265.         Key bottom 11 bits "iiiidddddss":
  266.                                 4 bits for sensor/command id (0-15), 5 bits for dimension (0-31), 2 bits for "sub-dimension” (0-3)
  267. ***************************************************************************************************************************
  268.         id=0:                retina event streaming (sub-dimension specify retina 0..3);
  269.                                 payload contains event encoded as p0000000.0yyyyyyy.00000000.0xxxxxxx
  270.                                 (for future larger retinas the "0"s can be used to extend range in x and y respectively)
  271.         id=1/2/3/4:        retina request on-board sensor data
  272.                                 dim=0..31 - type of sensory data (e.g. Gyro)
  273.                                 ss =0..3  - sensory axis (e.g. Gyro_rateX)
  274.                                 payload contains sensory data either "plain" or S16.15 as requested
  275.         id=5:                return digital IO signals, (sub-dimension specify retina 0..3)
  276. ***************************************************************************************************************************
  277.         id=8:                PushBot specific replies (none yet)
  278.                                 dim[4..3]= 28/24/20/16 UART/PushBot-ID (3..0)
  279.                                 dim[2..0]= unused (0..3)
  280.                                 ss       = unused (0..3)
  281. ***************************************************************************************************************************
  282.         id=9:                SpomniBot specific replies, on-board sensor data:
  283.                                 dim=0..31 - type of sensory data (e.g. Gyro)
  284.                                 ss =0..3  - sensory axis (e.g. Gyro_rateX)
  285.                                 payload contains sensory data either "plain" or S16.15 as requested
  286. ***************************************************************************************************************************
  287.         id=10:                BallBalancer request/read-back current angle
  288.                                 dim=0..31 - type of data (angle, velocity, current, ...)
  289.                                 ss =0..1  - direction X or Y
  290. ***************************************************************************************************************************
  291.         id=11:                Laser Mirror (none yet)
  292. ***************************************************************************************************************************
  293.       id=12: Myorobotics Motor Monitor and Sensor Data
  294.                         dim specifies the data source:
  295.                             dim bit 3:     source flag: motor monitor (cleared), sensor (set)
  296.                             dim bits 2..0: index (0..7) of data source
  297.                         subdimension specifies type of sensory data (only relevant for motor monitor)
  298.                             3: displacement, 2: current, 1: encoder Position, 0: omega
  299.                         payload contains data in int32 format
  300. ***************************************************************************************************************************
  301. ***************************************************************************************************************************
  302.         id=13..15:        free
RAW Paste Data
We use cookies for various purposes including analytics. By continuing to use Pastebin, you agree to our use of cookies as described in the Cookies Policy. OK, I Understand
 
Top