Inuktun Services Ltd.

ER-SP-I0013-09

October 21, 2013

ER-SP-I0013-13 Inuktun Version 2 Serial Protocol

Date: OCT 21, 2013 Note: this is revision 13 of this document. Changes in this revision:
1. Added speed position control method in Rotating Motor Position Control Interface.

Table of Contents
The Protocol .................................................................................................................................................. 1 Signaling rates ........................................................................................................................................... 1 Timing Constraints ..................................................................................................................................... 1 Coordinate System Definition .................................................................................................................... 1 Byte Ordering ............................................................................................................................................ 2 Definitions .................................................................................................................................................. 2 Philosophical Differences .......................................................................................................................... 2 Encapsulation ........................................................................................................................................ 2 Example: ................................................................................................................................................ 3 Real-World Units .................................................................................................................................... 3 Example: ................................................................................................................................................ 3 Packet Structure ........................................................................................................................................ 4 Standard packets ................................................................................................................................... 4 Group control packets ............................................................................................................................ 5 CRC Calculation ........................................................................................................................................ 5 The Interfaces ............................................................................................................................................... 6 Summary of the Interfaces ........................................................................................................................ 6 Administrative Interface (0x00) .................................................................................................................. 7 Identification .............................................................................................................................................. 7 Identify device configure (0x00) ............................................................................................................. 7 Identify Node ID configure (0x01) .......................................................................................................... 8 Ping (0x02) ............................................................................................................................................. 8 Ping Reply (0x03) .................................................................................................................................. 8 Identify and interrogate .............................................................................................................................. 9 Identify (0x04) ........................................................................................................................................ 9 Determining Supported Interfaces ............................................................................................................. 9 Enumerate supported interfaces (0x05) ................................................................................................ 9 Supported interfaces response (0x06)................................................................................................. 10

Page i

Inuktun Services Ltd.

ER-SP-I0013-09

October 21, 2013

Composite Packet Definition ................................................................................................................... 10 Subscribe to composite packet (0x07) ................................................................................................. 11 Unsubscribe from composite packet (0x08) ........................................................................................ 12 Remove all composite packet subscriptions (0x09) ............................................................................ 12 Composite packet subscription response (0x0a) ................................................................................. 12 Enumerate composite packet subscriptions (0x0b) ............................................................................. 13 Report composite packet subscriptions (0x0e) .................................................................................... 13 Firmware Version Request (0x0f) ........................................................................................................ 14 Firmware Version Reply (0x10) ........................................................................................................... 14 Environmental Parameter Interface (0x01) ............................................................................................. 15 Get Environmental Parameters (0x00) ................................................................................................ 15 Return Environmental Parameters (0x01) ........................................................................................... 16 Get Available Parameters (0x02) ......................................................................................................... 16 Return Available Parameters (0x03) .................................................................................................... 16 Set Zero Offsets (0x04)........................................................................................................................ 17 Amplitude Control Interface (0x02) .......................................................................................................... 18 Set Amplitude (0x00) ........................................................................................................................... 18 Amplitude Reply (0x01)........................................................................................................................ 18 Get Amplitude Control Parameter Info (0x02) ..................................................................................... 18 Return Amplitude Control Parameter Info (0x03) ................................................................................ 19 Closed Loop Rotating Machine Linear Motion Control Interface (0x03) ................................................. 20 Set Speed (0x00) ................................................................................................................................. 20 Set Speed Reply (0x01) ....................................................................................................................... 20 Get Closed Loop Rotating Machine Parameter Info (0x02)................................................................. 21 Return Closed Loop Rotating Machine Parameter Info (0x03)............................................................ 21 Set Raw Position (0x08) ...................................................................................................................... 21 Set Raw Position Reply (0x09) ......................................................................................................... 22 iGEMS Gamma Radiation Detector Interface (0x04) .............................................................................. 23 Get number of events in FIFO (0x04) .................................................................................................. 23 Return number of events in FIFO (0x84) ............................................................................................. 23 Success response (0xFE) .................................................................................................................... 23 Failure response (0xFF)....................................................................................................................... 24 Clear event FIFO (0x05) ...................................................................................................................... 24 Get iGEM unit number (0x0B) ............................................................................................................. 24 Return iGEM Unit Number (0x8B) ....................................................................................................... 24 Get detector type (0x0D) ..................................................................................................................... 25 Return iGEM Detector Type (0x8D) ..................................................................................................... 25

Page ii

Inuktun Services Ltd.

ER-SP-I0013-09

October 21, 2013

Get detector bias voltage (0x0F) ......................................................................................................... 25 Return detector bias voltage (0x8F) .................................................................................................... 25 Set ASIC Gain (0x10) .......................................................................................................................... 26 Set ASIC Shaping Time (0x11) ............................................................................................................ 26 Set High Voltage Level (0x12) ............................................................................................................. 26 Set FIFO Nearly Full Value (0x13) ....................................................................................................... 27 Enable/Disable Event Counter (0x14) ................................................................................................. 27 Read and Reset Event Counter (0x15)................................................................................................ 27 Return Event Count (0x95) .................................................................................................................. 28 Get N Events (0x40) ............................................................................................................................ 28 Return N Events (0xC0) ....................................................................................................................... 28 Rotating Motor Position Control Interface (0x07) .................................................................................... 29 Set Position (0x00) ............................................................................................................................... 29 Set Position Reply (0x01) .................................................................................................................... 29 Get Position Control Parameter Info (0x02)......................................................................................... 30 Return Position Control Parameter Info (0x03) ................................................................................... 30 Move to Reset Position (0x04) ............................................................................................................. 30 Verify at Reset Position (0x05) ............................................................................................................ 31 Verify Reset Reply (0x06) .................................................................................................................... 31 Get Position (0x07) .............................................................................................................................. 31 Return Position (0x08) ......................................................................................................................... 32 Set Parameters (0x09) ......................................................................................................................... 32 Set Parameters Response (0x0a) ....................................................................................................... 32 Stop (0x0b) .......................................................................................................................................... 32 Set Speed Position Control (0x0c) ....................................................................................................... 33 Speed Position Control Reply (0x0d) ................................................................................................... 33 Zero Position (0x0e)............................................................................................................................. 33 Zero Position Reply(0x0f) ................................................................................................................. 34 Auxiliary Control Interface (0x08) ............................................................................................................ 34 Arm Raise Control Set (0x00) .............................................................................................................. 34 Arm Raise Control Reply (0x01) .......................................................................................................... 35 Arm Raise Calibration Set (0x02) ..................................................................................................... 35 Arm Raise Calibration Reply (0x03) ................................................................................................. 36 Lights Control Interface (0x09) ................................................................................................................ 36 Set Light Control (0x00) ....................................................................................................................... 36 Light Control Reply (0x01) ................................................................................................................... 36 Get Light Parameter Info (0x02) .......................................................................................................... 37

Page iii

Inuktun Services Ltd.

ER-SP-I0013-09

October 21, 2013

Return Lights Parameter Info (0x03) ................................................................................................... 37 Error Interface (0xFF) .............................................................................................................................. 37 Throw (0x00) ........................................................................................................................................ 38 Various Comments, Notes, Things to Do .................................................................................................... 38

Page iv

Inuktun Services Ltd.

ER-SP-I0013-09

October 21, 2013

The Protocol
This protocol is an adaptation of the serial protocol described in ER-SP-I0011-01. It extends the old protocol to handle the following: Addressing same-type components: with the old protocol, it was not possible to have two of the same type of component (two SP90s, for example) on the same bus. Run-time discovery of components on the bus: the new protocol describes the process by which components are enumerated. Allowing this to happen at run-time makes it possible to have "plug and play" components. Run-time formation of ad-hoc groups: allows arbitrary groups of components (all forward-facing lights, for example) to be controlled in unison. Ad-hoc commands: allows simultaneous control of dissimilar components.

For consistency with the previous version of the protocol, one can assume that controller means host, and vice versa. In either version, the most natural implementation is to have a single controller, but there is nothing to prevent using multiple controllers, so long as they coordinate between themselves to avoid bus contention. In the case of a single controller, the convention is for it to be node 0. Data is sent to and from the host in packets of bytes. Each packet starts with a start byte and ends with a 2-byte CRC. The maximum packet length is 255 bytes. Data flow is governed by the controller/host. All other components will transmit only if they have received a valid packet directed at them.

Signaling rates
The communication protocol is based on RS485 voltage levels and asynchronous, 38,400 bps, 1 start bit, 8 data bits, 1 stop bit signaling.

Timing Constraints
Name Reply Packet Latency Host Packet Period Receive Packet Timeout Receive Byte Timeout Min (ms) Typical (ms) Max (ms) 10 Description The time between a host request and a slave reply The time between the host sending requests under normal conditions The time after which the host may assume a packet loss after sending a request and waiting for a reply The time after which the host may assume an incomplete packet and attempt to send a new one

75 100

30

Coordinate System Definition

By definition, x extends from the front of the component, y extends to the right, and z extends from the bottom. So, for example, giving an ROV a command of [+1, -1, +1] would cause it to move forward and to the left, while diving. Rationale: x extending from the front of the vehicle aligns the nose of a vehicle with its heading. Further, heading angle increases when turning clockwise, so y must be to the right. While it may seem more intuitive for z to extend up, rather than down, this would break the right hand rule. Adherence to the right hand rule is important so that coordinate transforms can be performed via matrix multiplication.

Page 1

Inuktun Services Ltd.

ER-SP-I0013-09

October 21, 2013

Roll is the angle about the x axis, pitch is the angle about the y axis, and yaw is the angle about the z axis. Sign convention is, again, determined by the right hand rule. Note that this system matches exactly the sign conventions expressed in ER-SP-I0011-01.

Byte Ordering
On-the-wire byte ordering shall follow network byte ordering convention. In other words, all data types should be transmitted most significant byte first. In C, hton and ntoh functions provide this mapping.

Definitions
The following definitions are for a device, which can be assumed to be a microcontroller that is in communication with a controller on the RS-485 bus. Node id (byte type) Similar in concept to an IP address. Nodes can have ids in the range [0, 127], allowing for a system to be comprised of up to 128 devices. Prior to configuration, a node will have the id 255, which signifies that it has not yet been assigned a proper node id. Given the limitations of RS-485 signaling, allowing a larger range (thus demanding a larger data type) would probably produce little benefit. All packets are sent from node to [group of] node(s). Physical address (UInt32 type) Similar in concept, though not purpose, to a MAC address. This is a non-volatile, semi-permanent id for a particular component. It is intended to be set during production, and provides a means to discriminate between components that are grouped together into something that is given a serial number. Thus, a Minitrac-2XL might have a single serial number, but it would have two motor drivers, each with their own physical address. Unlike in Ethernet, this is not used for routing, but solely for bootstrapping to the point that the device can be given a Node id. Each and every microcontrolled device manufactured by Inuktun should have a unique machine address. Serial number (UInt32 type) This is the standard Inuktun serial number that is given to a device. It is not necessarily unique, because it is in theory possible that a product made by Inuktun with a single serial number may include more than one device, each of which will have the same serial number but different machine addresses. Group (byte type) A plurality of nodes that, for some reason, is convenient to treat collectively. Group ids are used in place of Node ids, and can have the range [128, 255]. The node id 255 is defined to be the broadcast / all nodes group. Interface (UInt16 type) A collection of methods supported by a component. A component may support more than one interface. Subcomponent (byte type) This index is used to identify components within a single device that implement the same interface. For example a single device may control two banks of lights each of which is independent of the other. Most interfaces will only be implemented by the root subcomponent, which is zero. Method (byte type) These describe the methods provided by the interface.

Philosophical Differences
Encapsulation
While it would be possible to map almost directly the commands described in ER-SP-E0012-02 into this protocol, to do so would belie the power that abstracting to interfaces provides. Further, enforcing good encapsulation of objects (both real-world and abstract) will be beneficial, both for flexibility when building custom systems from modular components, and for improving code maintainability.

Page 2

Inuktun Services Ltd.

ER-SP-I0013-09

October 21, 2013

Example:
A Spectrum 90 is actually a pan/tilt gimbal, camera, light source, and possibly laser striper all rolled into one. So, under this paradigm, it would implement at least three separate interfaces. A forward-viewing camera would be similar, but simply not implement pan/tilt. Now, assume Sony develops another camera block that is size-compatible with the one currently used in the SP90, but offers a nifty new auto focus mode, or more powerful zoom, or some such feature. It would be only the camera interface that would need to be adapted, and, provided that the additional features were purely an extension of the blocks features, the camera could simultaneously implement both the old and new interfaces for the camera block. Notice that this also provides a mechanism to address options. If the particular SP90 has lasers, then it will implement that interface; otherwise it wont.

Real-World Units
Rather than using units that favor efficiency of conversion or convenience to the embedded programmer, components should use units that have real-world significance. A direct result of this is that a quantitys natural representation may not be a whole number. The jump to floating point has its drawbacks, most notably in efficiency, but it offers the most flexibility and natural representation.

Example:
When expressing the commanded speed for a track, it might be tempting to express this value as a single byte, with +127 meaning full forward, and -127 meaning full reverse. Thus, the resolution (and unit of th measurement) is 1/127 of the tracks full speed. The difficulty comes when it is desired to mix this track with a track of another type on a particular system, and the tracks have differing top speeds. If the two are to look to the same command for their speed, they must use a shared representation. Taking this one step further, it only makes sense if this shared representation also carries some real-world significance. Without question, the system of units for such measurements should be SI. One could easily go overboard with this, however. Theres not much cause to command li ght intensity in terms of candela, for instance. The number isnt likely to have meaning for the operator, and a group of lights commanded to do the same thing probably should be commanded as a fraction of their full intensity.

Page 3

Inuktun Services Ltd.

ER-SP-I0013-09

October 21, 2013

Packet Structure
Standard packets
All packets except group control packets must have the following structure: Byte 0 Name Start byte Description All packets begin with this value. It serves as a marker, and helps to synchronize UARTs with auto baud rate detection The length of the packet (including start byte and CRCs), in bytes Value 0xAA

Length (in bytes)

2 3 4 5-6 7 [8, 8+n)

Destination node Source node Subcomponent Interface / Component Method Data

The node id or group id of the receiver(s) The senders node id The subcomponent (within the node) that is being addressed The interface upon which the method is being called The number of the method within the interface The parameters of the method

[10, 255]. Each node shall be able to cope with packets having lengths up to 255 being present on the bus, but the size of a nodes receive buffer may dictate that it is not able to itself receive such a large packet. 32 or 64 would be a much more practical expectation. Group or node id; [0, 255] Node id; [0, 127] [0, 255] [0, 65535] [0, 255] Byte array with arbitrary contents, having length, n, in the range [0, 245] [0, 255] [0, 255]

8+n 9+n

CRCH CRCL

The most significant byte of the CRC. The least significant byte of the CRC.

Page 4

Inuktun Services Ltd.

ER-SP-I0013-09

October 21, 2013

Group control packets

Group control packets must have the following structure: Byte 0 Name Start byte Description All packets begin with this value. It serves as a marker, and helps to synchronize UARTs with auto baud rate detection The length of the packet (including start byte and CRCs), in bytes Value 0xAA

Length (in bytes)

2 3 4 [5, 5+n)

Destination node Source node Response Index Data

The group id of the receiver(s) The senders node id Parameters of the method used by the group, possibly for each node in the group. The most significant byte of the CRC. The least significant byte of the CRC.

8+n 9+n

CRCH CRCL

[10, 255]. Each group shall be able to cope with packets having lengths up to 255 being present on the bus, but the size of a nodes receive buffer may dictate that it is not able to itself receive such a large packet. 32 or 64 would be a much more practical expectation. Group id; [128, 254] Node id; [0, 127] [0, 250] Byte array with arbitrary contents, having length, n, in the range [0, 245] [0, 255] [0, 255]

CRC Calculation
The CRC is calculated using the polynomial X^16 + X^12 + X^5 + 1. To calculate the CRC, use the following pseudo-code: Preload the CRC accumulator with 0xFFFF. For each bit to be checked, as in the order of appearance on the wire { Left shift the current bit of the message into the CRC accumulator If the CRC accumulator overflows (the 16th bit is one) { XOR the CRC accumulator with 0x1021 } Mask the CRC accumulator to the bottom 16 bits } Important note: The CRC bytes should not be included in the CRC calculation (how could they be?). Implementation note: Should a component receive a packet having a CRC mismatch, it should silently ignore the packet. After all, it cannot even be sure the packet was intended for it. Should the packet have had a response, the controller will timeout, and retransmit if necessary.

Page 5

Inuktun Services Ltd.

ER-SP-I0013-09

October 21, 2013

The Interfaces
Summary of the Interfaces
Interface Name Administrative Environmental Parameter Amplitude Control Closed Loop Rotating Machine Linear Motion IGEMS Gamma Radiation Detector Position Control Error Number (hex) 00 01 02 03 04 07 FF Number of Methods 16 5 4 4 20 11 1

Table 1: Summary of the Interfaces

Page 6

Inuktun Services Ltd.

ER-SP-I0013-09

October 21, 2013

Administrative Interface (0x00)

Under this protocol, there are a number of administrative functions that every node must be able to perform. These functions (methods) are collected under the administrative interface, which has id = 0x00. Support of this interface, by all components, is mandatory.

Identification
The nodes on the system are to be discoverable at run-time. While some user interaction may be required to actually use a newly-inserted component, the system shall be able to detect and communicate with the component with no operator intervention beyond instructing the system to scan for new components. To ensure that all devices will be discovered, devices must implement some means of avoiding or recovering from collisions on the bus during discovery. Physical address byes definition: Byte Description 1 Physical address 2 Physical address 3 Physical address 4 Device type

0: Camera 1: Track(AF) 2: Telemetry can(BH) 3: Traction enhancement

Identify device configure (0x00)

Byte 1 2 3 4 5-6 7 8-11 12-15 16-19 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Serial number New Physical address New Serial number Description The length of the packet The responding nodes id The senders node id The root subcomponent Administrative Identify device configure The serial number of the piece of equipment containing the node The physical address of the node The serial number of the piece of equipment containing the node Value 22 [0, 127] or 255 [0, 127] 0 0x00 0x00 [1, 2147483648] [1, 2147483648] [1, 2147483648]

Response: None Upon reception of a Identify device configure packet, the device will update its physical address and serial number to those provided only when packet serial number=0xffffffff or device serial number is equal to the packet serial number. This packet could be used in production to save a serial number and machine address to a device.

Page 7

Inuktun Services Ltd.

ER-SP-I0013-09

October 21, 2013

Identify Node ID configure (0x01)

Byte 1 2 3 4 5-6 7 8-11 12 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Serial number New node id Description The length of the packet The responding nodes id The senders node id The root subcomponent Administrative Identify Node ID configure (extended ack) The serial number of the piece of equipment containing the node A new node id that the responding node should assume upon packet reception Value 15 [0, 127] or 255 [0, 127] 0 0x00 0x01 [1, 2147483648] [0, 127]

Response: None Upon reception of a Identify Node ID configure packet, the node shall immediately assume the new node ID and consider the discovery process successful only when packet serial number=0xffffffff or device serial number is equal to the packet serial number.

Ping (0x02)
Byte 1 2 3 4 5-6 7 8-11 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Serial number Description The length of the packet The responding nodes id The senders node id The root subcomponent Administrative Ping The serial number of the piece of equipment containing the node Value 14 [1, 127] ,255 [1, 127] 0 0x00 0x02 [0, 255]

Response: Ping Reply This method is a quick way to get information that a node is available and configured, and to ensure that information about a node is current and correct.

Ping Reply (0x03)

Byte 1 2 3 4 5-6 7 8-11 12-15 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Physical address Serial number Description The length of the packet The responding nodes id The senders node id The root subcomponent Administrative Ping Reply The physical address of the node The serial number of the piece of equipment containing the node Value 18 [0, 127] [0, 127] 0 0x00 0x03 [1, 2147483648] [1, 2147483648]

Response: none

Page 8

Inuktun Services Ltd.

ER-SP-I0013-09

October 21, 2013

Identify and interrogate Identify (0x04)

Byte 1 2 3 4 5-6 7 8 Name Length (in bytes) Destination node Source node Subcomponent Interface Method ID number / on/off Description The length of the packet The responding nodes id The senders node id The root subcomponent Administrative Identify A number that the node should try to convey to the user Value 11 [0, 127] [0, 127] 0 0x00 0x04 [0, 255] 0 = off, otherwise on

Response: None Provides another means for the user to match a node ID with an actual piece of equipment. When id number is non-zero, the node shall attempt to identify itself by some means native to it. If its a light source, it might flash, for example. Optionally, the device may try to convey the number, by flashing in bursts of long and short flashes, for example.

Determining Supported Interfaces

Considering components in terms of the interfaces they support is useful in that it enhances encapsulation, but it also has the benefit of allowing interaction of components that were not designed with each other in mind. In this way, a joystick that was designed to control a pan/tilt gimbal should be able to control any gimbals supporting the pan/tilt interface, regardless of model of camera (or other sensor/effector) payload. However, in order to do this, the joystick must be able to determine that a Spectrum 200 has pan/tilt capability, even though it may have been designed before the Spectrum 200 was even conceived. To accomplish this, components shall be capable of being queried for the interfaces they support. This is accomplished via the Enumerate supported interfaces command.

Enumerate supported interfaces (0x05)

Byte 1 2 3 4 5-6 7 8 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Page Description The length of the packet The responding nodes id The senders node id The root subcomponent Administrative Enumerate supported interfaces The page of interfaces the requester is interested in Value 11 [0, 127] [0, 127] 0 0x00 0x05 [0, 255]

Response: Supported interfaces response Recalling that packets can have a maximum length of 255 bytes, and many components may use buffers substantially smaller, it may take several packets to fully enumerate all of the supported interfaces. The page argument is used to specify with which group of n (where n can vary between 1 and 122) interfaces the component should reply.

Page 9

Inuktun Services Ltd.

ER-SP-I0013-09

October 21, 2013

Supported interfaces response (0x06)

Byte 1 2 3 4 5-6 7 8 9-10 11 12-13 14 Response: None Implementation note: Support for the administrative interface (0x00) is assumed, and need not be included. The Supported interfaces packet, like all others, must include a two-byte CRC. Name Length (in bytes) Destination node Source node Subcomponent Interface Method Last page Interface 0 Subcomponent 0 Interface 1 Subcomponent 1 Description The length of the packet The responding nodes id The senders node id The root subcomponent Administrative Supported interfaces response Is this that last page of interfaces The first supported interface The subcomponent of the first supported interface The second supported interface The subcomponent of the second supported interface Value 13+ [0, 127] [0, 127] 0 0x00 0x06 0 not last page 1 last page [1, 65535] [0,255] [1, 65535] [0,255]

Composite Packet Definition

A key difference between this protocol and those that have preceded it is that this one is extensible at run time. In this way, components can be assembled together to create custom systems, without having to modify the firmware of the individual components to be aware of the context in which they are operating. In its simplest incarnation, this can be used to for grouping. For instance, two microcontrolled lights on a system can be placed in a group, headlights, and they will respond to the same intensity command appearing on the RS-485 bus. Of course, it would also be possible to set the intensities by communicating with the lights individually, but this is less desirable in that it i) wastes bandwidth, and ii) means that the lights will not actually be changing at the same time. Simultaneous execution isnt particularly important in the case of controlling lights, but it can make a difference for components where motion is involved. In addition to simple grouping, this mechanism can be used to allow stock components to be used in a number of different systems without having to reprogram them. In this way, both a microcontrolled VT150 1 and a Hydra system would have respective VT150 and Hydra custom vehicle command packets. A component such as a track could be moved between the two systems, with minimal reconfiguration.

In Greek mythology, a snake-like monster with 9 heads. Those familiar with Inuktun mythology will tell stories of a mythical system with nine cameras, between three and nine tracks, and a tail that went on for miles.

Page 10

Inuktun Services Ltd.

ER-SP-I0013-09

October 21, 2013

Subscribe to composite packet (0x07)

Byte 1 2 3 4 5-6 7 8 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Group Description The length of the packet The responding nodes id The senders node id The subcomponent (within the node) that is being addressed Administrative Subscribe to composite packet The composite node that will over which this packet has influence The index of the start of the parameters of the native command within the composite packet The interface of the native command The method of the native command The number of response packets that should occur before the node should respond Value 16 [0, 127] [0, 127] [0, 255] 0x00 0x07 [128, 254]

Packet index

[0, 250], but packets must be kept to within the size of the devices receive buffer [0, 65535] [0, 255] [0, 255], but realistically probably no more than 10. 255 signifies do not respond.

10-11 12 13

Native interface Native method Response index

Response: Composite packet subscription response Upon reception of a Subscribe to composite packet, the component shall react to incoming packets with the subscribed group. When such a packet is received, the component will interpret the data at packet index as a command having interface native interface and method native method. Should response index be less than 255, the component will reply to the commanded packet after response index other components have already done so. In this way, any subset of the components subscribed to the composite command can be made to respond, in turn. Trivial grouping would be implemented by having multiple components look to the same packet index for their command. It is intended that components persist their subscriptions between power interruptions, presumably by writing them into EE-PROM. This would require 6 bytes per subscription.

Page 11

Inuktun Services Ltd.

ER-SP-I0013-09

October 21, 2013

Unsubscribe from composite packet (0x08)

Byte 1 2 3 4 5-6 7 8 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Group Description The length of the packet The responding nodes id The senders node id The subcomponent (within the node) that is being addressed Administrative Unsubscribe from composite packet The composite node that will over which this packet has influence The index of the start of the native command within the composite packet Value 12 [0, 127] [0, 127] [0, 255] 0x00 0x08 [128, 254]

Packet index

[0, 250], but packets must be kept to within the size of the devices receive buffer

Response: Composite packet subscription response Upon reception of an Unsubscribe from composite packet packet, the component shall no longer look to packet index upon an incoming packet with the subscribed group. Note that a component may be made to subscribe to the same group multiple times, so as to react to multiple commands embedded in the composite packet. The correct behavior for an unsubscribe command is to remove only the subscription looking to packet index, and not to remove all subscriptions of the particular group.

Remove all composite packet subscriptions (0x09)

Byte 1 2 3 4 5-6 7 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Description The length of the packet The responding nodes id The senders node id The subcomponent (within the node) that is being addressed Administrative Remove all composite packet subscriptions Value 10 [0, 127] [0, 127] [0, 255] 0x00 0x09

Response: Composite packet subscription response

Composite packet subscription response (0x0a)

Byte 1 2 3 4 5-6 7 8 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Return code Description The length of the packet The responding nodes id The senders node id The subcomponent (within the node) that is being addressed Administrative Composite packet subscription response Was the component able to subscribe to the composite command Value 11 [0, 127] [0, 127] [0, 255] 0x00 0x0a 0x00 = success, otherwise failure

Response: None

Page 12

Inuktun Services Ltd.

ER-SP-I0013-09

October 21, 2013

Enumerate composite packet subscriptions (0x0b)

Byte 1 2 3 4 5-6 7 8 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Page Description The length of the packet The responding nodes id The senders node id The subcomponent (within the node) that is being addressed Administrative Enumerate composite packet subscriptions The page of subscriptions the requester is interested in Value 11 [0, 127] [0, 127] [0, 255] 0x00 0x0b [0, 255]

Response: Composite packet subscriptions

Report composite packet subscriptions (0x0e)

Byte 1 2 3 4-5 6 7 8 Name Length (in bytes) Destination node Source node Interface Method Last page Group1 Packet index1 Description The length of the packet The responding nodes id The senders node id Administrative Report composite packet subscriptions Is this that last page of interfaces The composite node that will over which this packet has influence The index of the start of the native command within the composite packet The interface of the native command The method of the native command The number of response packets that should occur before the node should respond The composite node that will over which this packet has influence The index of the start of the native command within the composite packet The interface of the native command The method of the native command The number of response packets that should occur before the node should respond Value 16+ [0, 127] [0, 127] 0x00 0x0e 0 not last page 1 last page [128, 254]

10-11 12 13

Native interface1 Native method1 Response index1 Group2

[0, 250], but packets must be kept to within the size of the devices receive buffer [0, 65535] [0, 255] [0, 255], but realistically probably no more than 10. 255 signifies do not respond. [128, 254]

14

15

Packet index2 Native interface2 Native method2 Response index2

16-17 18 19

[0, 250], but packets must be kept to within the size of the devices receive buffer [0, 65535] [0, 255] [0, 255], but realistically probably no more than 10. 255 signifies do not respond.

Response: None

Page 13

Inuktun Services Ltd.

ER-SP-I0013-09

October 21, 2013

Firmware Version Request (0x0f)

Byte 1 2 3 4 5-6 7 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Description The length of the packet The responding nodes id The senders node id The root subcomponent Administrative Firmware Version Request Value 10 [0, 127] [0, 127] 0 0x00 0x0f

Response: Firmware Version Reply

Firmware Version Reply (0x10)

Byte 1 2 3 4 5-6 7 8 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Version Number Description The length of the packet The responding nodes id The senders node id The root subcomponent Administrative Ping Reply Value 11 [0, 127] [0, 127] 0 0x00 0x10 [0, 255]

Page 14

Inuktun Services Ltd.

ER-SP-I0013-09

October 21, 2013

Environmental Parameter Interface (0x01)

This interface is used to get information from various sensors that are included in a device, but are not feedback parameters from other interfaces. Up to 16 parameters can be returned at once, always as floats and always in real-world units. The available parameters in an interface are specified by a 16-bit unsigned integer. If the bit corresponding to a parameter is set, then the parameter is available. Available parameters are described in the following table. Bit Position 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 Parameter Temperature Humidity Voltage input Voltage output Current Input Current Output Pitch Roll Gyro X Rate Gyro Y Rate Gyro Z Rate Gas concentration Depth Flow speed Power State Unit Celsius Degrees Percent Relative Humidity Volts Volts Amperes Amperes Degrees Degrees Degrees/sec Degrees/sec Degrees/sec Percent full-scale Meters Meters/second 00:Normal, 01:DC1 Fault. 02:DC2 Fault. 03:DC1 and DC2 Fault. Encoder Counts

15

Position Sensor

The interface includes four methods, Get Environmental Parameters, Return Environmental Parameters, Get Available Parameters, and Return Available Parameters.

Get Environmental Parameters (0x00)

Byte 1 2 3 4 5-6 7 8-9 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Parameter Mask Description The length of the packet The responding nodes id The senders node id The interface subcomponent Environmental Parameter Interface Get Parameters Bit mask showing the parameters to return. Value 12 [0, 127] [0, 127] [0, 255] 0x01 0x00 UInt16 [1, 65535]

Response: Return Environmental Parameters

Page 15

Inuktun Services Ltd.

ER-SP-I0013-09

October 21, 2013

Return Environmental Parameters (0x01)

Byte 1 2 3 4 5-6 7 8-11 12-15 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Parameter 1 Parameter 2 Parameter n Description The length of the packet The responding nodes id The senders node id The interface subcomponent Environmental Parameter Interface Get Parameters Reply Parameter corresponding to lowest nonzero bit value Parameter corresponding to next lowest nonzero bit value Parameter corresponding to last bit value Value 10 + 4 * n [0, 127] [0, 127] [0, 255] 0x01 0x01 Float Float Float

Response: none

Get Available Parameters (0x02)

Byte 1 2 3 4 5-6 7 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Description The length of the packet The responding nodes id The senders node id The interface subcomponent Environmental Parameter Interface Get Available Parameters Value 10 [0, 127] [0, 127] [0, 255] 0x01 0x02

Response: Return Available Parameters

Return Available Parameters (0x03)

Byte 1 2 3 4 5-6 7 8-9 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Parameter Mask Description The length of the packet The responding nodes id The senders node id The interface subcomponent Environmental Parameter Interface Return Available Parameters Bit mask showing the available parameters Value 12 [0, 127] [0, 127] [0, 255] 0x01 0x03 UInt16 [1, 65535]

Response: none

Page 16

Inuktun Services Ltd.

ER-SP-I0013-09

October 21, 2013

Set Zero Offsets (0x04)

Byte 1 2 3 4 5-6 7 8-9 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Parameter Mask Description The length of the packet The responding nodes id The senders node id The interface subcomponent Environmental Parameter Interface Set Zero Offsets Bit mask showing the parameters to set offsets for. Value 12 [0, 127] [0, 127] [0, 255] 0x01 0x04 UInt16 [1, 65535]

Response: None

Set Motor Torque Limit (0x0c)

Byte 1 2 3 4 5-6 7 8 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Torque limit Description The length of the packet The responding nodes id The senders node id The interface subcomponent Environmental Parameter Interface Set Motor Torque Limit Value 11 [0, 127] [0, 127] [0, 255] 0x01 0x0c 0-100

Response: Motor Torque Limit Reply

Read Motor Torque Limit (0x0d)

Byte 1 2 3 4 5-6 7 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Description The length of the packet The responding nodes id The senders node id The interface subcomponent Environmental Parameter Interface Read Motor Torque Limit Value 10 [0, 127] [0, 127] [0, 255] 0x01 0x0d

Response: Motor Torque Limit Reply

Motor Torque Limit Reply (0x0e)

Byte 1 2 3 4 5-6 7 8 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Torque limit Description The length of the packet The responding nodes id The senders node id The interface subcomponent Environmental Parameter Interface Motor Torque Limit Reply Value 11 [0, 127] [0, 127] [0, 255] 0x01 0x0e 0-100

Response: none

Page 17

Inuktun Services Ltd.

ER-SP-I0013-09

October 21, 2013

Amplitude Control Interface (0x02)

This interface is for controlling amplitude-varying devices such as motors and lights. The interface has four methods, described below. The amplitude of the device being controlled is set using a floating point value that can vary between a minimum and a maximum value. Both minimum and maximum must be in the range [-1.0, 1.0], and the maximum must be greater than the minimum. The Set Amplitude command tells the device where to set its output, and the device responds with the Amplitude Reply packet containing the value of one or two optional feedback parameters. These feedback parameters can be either voltage (Volts) or current (Amperes). The Get Amplitude Control Parameter Info packet asks the device to respond with the Return Amplitude Control Parameter Info packet, containing the maximum and minimum values in effect for the device, a one-byte code indicating the type of device being controlled, and the definition of the feedback parameter types.

Set Amplitude (0x00)

Byte 1 2 3 4 5-6 7 8-11 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Amplitude Description The length of the packet The responding nodes id The senders node id The interface subcomponent Amplitude Control Set Amplitude The desired amplitude Value 14 [0, 127] [0, 127] [0, 255] 0x02 0x00 Float [Minimum, Maximum]

Response: Amplitude Reply

Amplitude Reply (0x01)

Byte 1 2 3 4 5-6 7 8-11 12-15 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Feedback parameter 1 Feedback parameter 2 Description The length of the packet The responding nodes id The senders node id The interface subcomponent Amplitude Control Set Amplitude Reply Feedback parameter 1 value (optional) Feedback parameter 2 value (optional) Value 10, 14 or 18 [0, 127] [0, 127] [0, 255] 0x02 0x01 Float Float

Response: none

Get Amplitude Control Parameter Info (0x02)

Byte 1 2 3 4 5-6 7 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Description The length of the packet The responding nodes id The senders node id The interface subcomponent Amplitude Control Get Parameters Value 10 [0, 127] [0, 127] [0, 255] 0x02 0x02

Response: Return Amplitude Control Parameter Info

Page 18

Inuktun Services Ltd.

ER-SP-I0013-09

October 21, 2013

Return Amplitude Control Parameter Info (0x03)

Byte 1 2 3 4 5-6 7 8-11 12-15 16 17 18 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Maximum Minimum Interface type Parameter 1 type Parameter 2 type Description The length of the packet The responding nodes id The senders node id The interface subcomponent Amplitude Control Return Parameters The maximum value in effect The minimum value in effect The type of device being controlled Feedback parameter 1 type Feedback parameter 2 type Value 21 [0, 127] [0, 127] [0, 255] 0x02 0x03 Float [-1.0, 1.0] Float [-1.0, 1.0] See below for codes V or A or X if not present V or A or X if not present

Response: none Possible codes for device type include M for Minitracs, and L for lights.

Page 19

Inuktun Services Ltd.

ER-SP-I0013-09

October 21, 2013

Closed Loop Rotating Machine Linear Motion Control Interface (0x03)

This interface is for controlling a linear motion device driven by a rotating machine such as an electric motor. It is assumed that the rotating machine includes an encoder that counts the rotations of the machine in some way such that the absolute speed of the device can be known and controlled. The interface has four methods, described below. The speed of the device being controlled is set using a floating point value that can vary between a minimum and a maximum value. Both minimum and maximum must be in real-world units of meters per second, and the maximum must be greater than the minimum. The Set Speed command tells the device how fast to go and in which direction (if the device has the capacity for bidirectional motion), and the device responds with the Set Speed Reply packet containing information about the current state of the rotating machine and the value of two optional feedback parameters. These feedback parameters can be either voltage (Volts) or current (Amperes). The Get Closed Loop Rotating Machine Parameter Info packet asks the device to respond with the Return Closed Loop Rotating Machine Parameter Info packet, containing the maximum and minimum speeds in effect for the device, calibration information for the encoder, and the definition of the optional feedback parameter types.

Set Speed (0x00)

Byte 1 2 3 4 5-6 7 8-11 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Speed Description The length of the packet The responding nodes id The senders node id The interface subcomponent Closed Loop Rotating Machine Linear Motion Control Interface Set Speed The desired speed (meters/sec) Value 14 [0, 127] [0, 127] [0, 255] 0x03 0x00 Float [Minimum, Maximum]

Response: Set Speed Reply

Set Speed Reply (0x01)

Byte 1 2 3 4 5-6 7 8-11 12-15 16-19 20-23 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Speed Total_Counts Feedback parameter 1 Feedback parameter 2 Description The length of the packet The responding nodes id The senders node id The interface subcomponent Closed Loop Rotating Machine Linear Motion Control Interface Set Speed Reply Track speed(Meters /Min) Cumulative encoder counts Feedback parameter 1 value (optional) Feedback parameter 1 value (optional Value 18, 22 or 26 [0, 127] [0, 127] [0, 255] 0x03 0x01 Positive or negative Float UInt32 Float Float

Response: none

Page 20

Inuktun Services Ltd.

ER-SP-I0013-09

October 21, 2013

Get Closed Loop Rotating Machine Parameter Info (0x02)

Byte 1 2 3 4 5-6 7 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Description The length of the packet The responding nodes id The senders node id The interface subcomponent Closed Loop Rotating Machine Linear Motion Control Interface Get Parameters Value 10 [0, 127] [0, 127] [0, 255] 0x03 0x02

Response: Return Closed Loop Rotating Machine Parameter Info

Return Closed Loop Rotating Machine Parameter Info (0x03)

Byte 1 2 3 4 5-6 7 8-11 12-15 16-17 18-21 22 23 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Maximum Minimum Counts/rev Revs/meter Parameter 1 Parameter 2 Description The length of the packet The responding nodes id The senders node id The interface subcomponent Closed Loop Rotating Machine Linear Motion Control Interface Return Parameters The maximum speed (m/s) The minimum speed (m/s) Encoder counts per revolution Motor revolutions/meter Feedback parameter 1 type Feedback parameter 2 type Value 26 [0, 127] [0, 127] [0, 255] 0x03 0x03 Float Float UInt16 [1, 65535] Float V or A or X if not present V or A or X if not present

Response: none

Set Raw Position (0x08)

Byte 1 2 3 4 5-6 Name Length (in bytes) Destination node Source node Subcomponent Interface Description The length of the packet The responding nodes id The senders node id The interface subcomponent Position Closed Loop Rotating Machine Linear Motion Control Interface Set Value The desired ADC Raw Value Value 15 [0, 127] [0, 127] [0, 255] 0x03

7 8-11 12

Method Position Reserved

0x08 Unit 32

Response: Set Position Reply, Over Current Position Reply.

Page 21

Inuktun Services Ltd.

ER-SP-I0013-09

October 21, 2013

Set Raw Position Reply (0x09)

Byte 1 2 3 4 5-6 7 8-11 12 13-16 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Raw Position Motor Direction Current Description The length of the packet The responding nodes id The senders node id The interface subcomponent Closed Loop Rotating Machine Linear Motion Control Interface Set Position Reply Position 0 Left /1 Right Motor Current Value 19 [0, 127] [0, 127] [0, 255] 0x03 0x09 Unit32 Unit8 Float

Response: none

Page 22

Inuktun Services Ltd.

ER-SP-I0013-09

October 21, 2013

iGEMS Gamma Radiation Detector Interface (0x04)

This interface is used to send commands to and get data from the iGEM sensor module from EV Products (www.evproducts.com). The method numbers are the same as the EV command numbers, and the method numbers of the responses to those commands are the same number plus 128.

Get number of events in FIFO (0x04)

Byte 1 2 3 4 5-6 7 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Description The length of the packet The responding nodes id The senders node id The interface subcomponent iGEMS Gamma Radiation Detector Interface Get number of events in FIFO Value 10 [0, 127] [0, 127] [0, 255] 0x04 0x04

Response: Return number of events in FIFO

Return number of events in FIFO (0x84)

Byte 1 2 3 4 5-6 7 8,9 Name Length (in bytes) Destination node Source node Subcomponent Interface Method # events Description The length of the packet The responding nodes id The senders node id The interface subcomponent iGEMS Gamma Radiation Detector Interface Return number of events in FIFO Number of events Value 12 [0, 127] [0, 127] [0, 255] 0x04 0x84 Uint16 [0, 2000]

Response: None Note that only up to 2000 events may be reported even though there are more available the FIFO depth is 5000 events.

Success response (0xFE)

Returned if the last method executed successfully. Byte 1 2 3 4 5-6 7 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Description The length of the packet The responding nodes id The senders node id The interface subcomponent iGEMS Gamma Radiation Detector Interface Return success Value 10 [0, 127] [0, 127] [0, 255] 0x04 0xfe

Response: None

Page 23

Inuktun Services Ltd.

ER-SP-I0013-09

October 21, 2013

Failure response (0xFF)

Returned if the last method did not execute successfully. Byte 1 2 3 4 5-6 7 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Description The length of the packet The responding nodes id The senders node id The interface subcomponent iGEMS Gamma Radiation Detector Interface Return failure Value 10 [0, 127] [0, 127] [0, 255] 0x04 0xff

Response: None

Clear event FIFO (0x05)

Clear the contents of the FIFO Byte 1 2 3 4 5-6 7 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Description The length of the packet The responding nodes id The senders node id The interface subcomponent iGEMS Gamma Radiation Detector Interface Clear event FIFO Value 10 [0, 127] [0, 127] [0, 255] 0x04 0x05

Response: Success response or failure response.

Get iGEM unit number (0x0B)

Returns the iGEM unit number. Byte 1 2 3 4 5-6 7 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Description The length of the packet The responding nodes id The senders node id The interface subcomponent iGEMS Gamma Radiation Detector Interface Get iGEM unit number Value 10 [0, 127] [0, 127] [0, 255] 0x04 0x0B

Response: Return iGEM Unit Number

Return iGEM Unit Number (0x8B)

Byte 1 2 3 4 5-6 7 8,9 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Unit # Description The length of the packet The responding nodes id The senders node id The interface subcomponent iGEMS Gamma Radiation Detector Interface Return iGEM unit number iGEM Unit number Value 12 [0, 127] [0, 127] [0, 255] 0x04 0x8B Uint16 [0, 65534]

Response: None

Page 24

Inuktun Services Ltd.

ER-SP-I0013-09

October 21, 2013

Get detector type (0x0D)

Gets the iGEM detector type. Byte 1 2 3 4 5-6 7 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Description The length of the packet The responding nodes id The senders node id The interface subcomponent iGEMS Gamma Radiation Detector Interface Get iGEM detector type Value 10 [0, 127] [0, 127] [0, 255] 0x04 0x0D

Response: Return iGEM Detector type

Return iGEM Detector Type (0x8D)

Byte 1 2 3 4 5-6 7 8 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Detector Description The length of the packet The responding nodes id The senders node id The interface subcomponent iGEMS Gamma Radiation Detector Interface Return iGEM Detector Type iGEM Detector Type Value 11 [0, 127] [0, 127] [0, 255] 0x04 0x8D Uint8 [1, 255]

Response: None Detector types are: 1 Capture plus; 2 CPG; 3 Planar.

Get detector bias voltage (0x0F)

Gets the iGEM detector bias voltage. Byte 1 2 3 4 5-6 7 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Description The length of the packet The responding nodes id The senders node id The interface subcomponent iGEMS Gamma Radiation Detector Interface Get detector bias voltage Value 10 [0, 127] [0, 127] [0, 255] 0x04 0x0F

Response: Return detector bias voltage

Return detector bias voltage (0x8F)

Byte 1 2 3 4 5-6 7 8 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Detector Description The length of the packet The responding nodes id The senders node id The interface subcomponent iGEMS Gamma Radiation Detector Interface Return detector bias voltage Detector bias voltage Value 12 [0, 127] [0, 127] [0, 255] 0x04 0x8F Uint16 [1, 2000]

Response: None

Page 25

Inuktun Services Ltd.

ER-SP-I0013-09

October 21, 2013

Detector bias voltage from 0 to 2000 is returned.

Set ASIC Gain (0x10)

Byte 1 2 3 4 5-6 7 8 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Gain Description The length of the packet The responding nodes id The senders node id The interface subcomponent iGEMS Gamma Radiation Detector Interface Set ASIC Gain ASIC Gain Value 11 [0, 127] [0, 127] [0, 255] 0x04 0x10 Uint8 [0, 1]

Response: Success response or Failure response Gains are: 0 18 mV/fC; 1 36 mV/fC.

Set ASIC Shaping Time (0x11)

Byte 1 2 3 4 5-6 7 8 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Shaping time Description The length of the packet The responding nodes id The senders node id The interface subcomponent iGEMS Gamma Radiation Detector Interface Set ASIC Shaping Time ASIC Shaping Time Value 11 [0, 127] [0, 127] [0, 255] 0x04 0x11 Uint8 [0, 1]

Response: Success response or Failure response Gains are: 0 12 s; 1 2.4 s.

Set High Voltage Level (0x12)

This command sets the output of the HV supply. Usually the value obtained from command 0x0F would be sent. Acceptable values range from 0 to 2047. Byte 1 2 3 4 5-6 7 8,9 Name Length (in bytes) Destination node Source node Subcomponent Interface Method HV Value Description The length of the packet The responding nodes id The senders node id The interface subcomponent iGEMS Gamma Radiation Detector Interface Set High Voltage Level Voltage of HV Supply Value 12 [0, 127] [0, 127] [0, 255] 0x04 0x12 Uint16 [0, 2047]

Response: None

Page 26

Inuktun Services Ltd.

ER-SP-I0013-09

October 21, 2013

Set FIFO Nearly Full Value (0x13)

This command is used to set the value where the FIFO nearly full signal line will transition from low to high. On power-up the iGEM SM will set this value to 0x0000 (0), FIFO nearly full signal line disabled. Byte 1 2 3 4 5-6 7 8,9 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Value Description The length of the packet The responding nodes id The senders node id The interface subcomponent iGEMS Gamma Radiation Detector Interface Set FIFO Nearly Full Value Nearly Full Value Value 12 [0, 127] [0, 127] [0, 255] 0x04 0x13 Uint16 [0, 5000]

Response: Success response or Failure response

Enable/Disable Event Counter (0x14)

This command is used to enable or disable the event counter. When the event counter is enabled, each over threshold event will increment a counter on the iGEM SM. The number of over threshold events recorded by this counter can be read out at any time using command 0x15. On power-up the event counter will be disabled. Byte 1 2 3 4 5-6 7 8 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Setting Description The length of the packet The responding nodes id The senders node id The interface subcomponent iGEMS Gamma Radiation Detector Interface Enable/Disable Event Counter Enable/Disable Value 11 [0, 127] [0, 127] [0, 255] 0x04 0x14 Uint8 [0, 1]

Response: Success response or Failure response Settings are: 0 disabled; 1 enabled.

Read and Reset Event Counter (0x15)

This command is used to read the value of the event counter via the SPI command interface. Once the event counter value is placed in the SPI transmit buffer, the counter is reset to 0 and over threshold event counting will resume. Byte 1 2 3 4 5-6 7 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Description The length of the packet The responding nodes id The senders node id The interface subcomponent iGEMS Gamma Radiation Detector Interface Read and Reset Event Counter Value 10 [0, 127] [0, 127] [0, 255] 0x04 0x15

Response: Success response or Failure response

Page 27

Inuktun Services Ltd.

ER-SP-I0013-09

October 21, 2013

Return Event Count (0x95)

This response returns the value of the event counter. Byte 1 2 3 4 5-6 7 8 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Count Description The length of the packet The responding nodes id The senders node id The interface subcomponent iGEMS Gamma Radiation Detector Interface Return Event Count Event Count Value 12 [0, 127] [0, 127] [0, 255] 0x04 0x95 Uint16 [0, 65535]

Response: Success response or Failure response

Get N Events (0x40)

This command is used to read the value of N events stored in the FIFO buffer. Each event is an integer less than 4096. N is any number less than 123 Byte 1 2 3 4 5-6 7 8 Name Length (in bytes) Destination node Source node Subcomponent Interface Method N Description The length of the packet The responding nodes id The senders node id The interface subcomponent iGEMS Gamma Radiation Detector Interface Get N Events Number of events to get Value 11 [0, 127] [0, 127] [0, 255] 0x04 0x40 Uint8 [1..122]

Response: Return N Events

Return N Events (0xC0)

This response returns the values of the events. Byte 1 2 3 4 5-6 7 8,9 10,11 .. Name Length (in bytes) Destination node Source node Subcomponent Interface Method Event0 Event1 .. Description The length of the packet The responding nodes id The senders node id The interface subcomponent iGEMS Gamma Radiation Detector Interface Return Event Count Event 0 Event 1 .. Value 10+N*2 [0, 127] [0, 127] [0, 255] 0x04 0xC0 Uint16 [0, 4095] Uint16 [0, 4095] Uint16 [0, 4095]

Response: None

Page 28

Inuktun Services Ltd.

ER-SP-I0013-09

October 21, 2013

Rotating Motor Position Control Interface (0x07)

This interface is for controlling devices that can be set to a range of positions by a rotating motor, the rotations of which are counted by an encoder of some sort. A constant of proportionality must exist between the encoder counts and the motor rotations, e.g. 256 encoder counts per revolution of the motor. All devices implementing this interface must have some method of moving to a known position (called the Reset Position) on command. On reaching the Reset Position the encoder counter must be set to zero. The position of the device being controlled is proportional (not necessarily linearly) to the number of rotations of the motor. In order to keep the firmware the same for all devices implementing this interface, a specific motor driving direction in an electronic sense (e.g. driving the motor in reverse) should result in the device moving toward its reset position. This implies that the minimum position (as measured by encoder counts) attainable by the device should be at its Reset Position. The interface has eleven methods, described below. The position of the device being controlled is set through a specific encoder count that can vary between zero and a maximum value. All devices implementing this interface are required to be at the reset position on power-up. If a device is not at the reset position on power-up, it should not be operable until moved to the reset position under operator control. The Set Parameters command is used to set the maximum encoder count for the device and the maximum speed at which the device should move to a new position. This command is normally only used at discovery, but could be used at any time to refresh or change those values. The Set Position command tells the device where to move to, and the device responds with the Set Position Reply packet containing the value of one or two optional feedback parameters. These feedback parameters can be a voltage (Volts) or a current (Amperes). The Get Position Control Parameter Info packet asks the device to respond with the Return Position Control Parameter Info packet, containing the encoder proportionality factor (counts per revolution), the maximum encoder count in effect for the device, the maximum speed of the motor, and the definition of the feedback parameter types. The Move to Reset Position command, and a Verify at Reset Position/Reply Verify Reset command/response pair are used to determine if the device is at the reset position. The Get Position/Return Position command/response pair are used to get the current position, expressed as an encoder count. Finally, the Stop command can be used at any time to stop the motor.

Set Position (0x00)

This command requests the device to move to a specified position, expressed as an encoder count. Depending on the difference between the current position and the new one, this movement could take some time. Byte 1 2 3 4 5-6 7 8-11 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Position Description The length of the packet The responding nodes id The senders node id The interface subcomponent Position Control Set Position The desired encoder count Value 14 [0, 127] [0, 127] [0, 255] 0x07 0x00 Int32 [0..Maximum]

Response: Set Position Reply

Set Position Reply (0x01)

This packet returns the current encoder count and up to two feedback parameters. The number of bytes returned by this reply will depend on whether 0, 1 or 2 feedback parameters have been specified in the Return Position Control Parameter Info packet.

Page 29

Inuktun Services Ltd. Byte 1 2 3 4 5-6 7 8-11 12-15 16-19 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Position Feedback parameter 1 Feedback parameter 2

ER-SP-I0013-09 Description The length of the packet The responding nodes id The senders node id The interface subcomponent Position Control Set Position Reply Current encoder counts Feedback parameter 1 value (optional) Feedback parameter 2 value (optional)

October 21, 2013 Value 14, 18 or 22 [0, 127] [0, 127] [0, 255] 0x07 0x01 Int32 [0..Maximum] Float Float

Response: none

Get Position Control Parameter Info (0x02)

Byte 1 2 3 4 5-6 7 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Description The length of the packet The responding nodes id The senders node id The interface subcomponent Position Control Get Position Control Parameter Info Value 10 [0, 127] [0, 127] [0, 255] 0x07 0x02

Response: Return Position Control Parameter Info

Return Position Control Parameter Info (0x03)

This interface gets information from the device as to the constant of proportionality between encoder counts and motor rotations, the maximum motor speed to use, and which, if any, parameters will be returned by the Set Position Reply method. Byte 1 2 3 4 5-6 7 8-9 10-13 14 15 16 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Counts/rotation Maximum Speed Parameter 1 type Parameter 2 type Description The length of the packet The responding nodes id The senders node id The interface subcomponent Position Control Return Position Control Parameter Info Encoder counts per rotation The maximum attainable count Maximum motor speed Feedback parameter 1 type Feedback parameter 2 type Value 19 [0, 127] [0, 127] [0, 255] 0x07 0x03 Uint16 Int32 Uint8[1..255] Character: see below for codes. Character: see below for codes.

Response: none Possible codes for parameter type include V for volts, A for amperes, and X for no parameter returned.

Move to Reset Position (0x04)

This interface is used to command the mechanical device to move to a known position. It may take some time for the mechanical device to move to this position. During the time that it takes to move to the reset

Page 30

Inuktun Services Ltd.

ER-SP-I0013-09

October 21, 2013

position, the device should ignore all commands except the Stop command and the Verify at Reset Position command. Byte 1 2 3 4 5-6 7 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Description The length of the packet The responding nodes id The senders node id The interface subcomponent Position Control Move to Reset Position Value 10 [0, 127] [0, 127] [0, 255] 0x07 0x04

Response: None

Verify at Reset Position (0x05)

This interface is used determine if the device is at the reset position. Byte 1 2 3 4 5-6 7 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Description The length of the packet The responding nodes id The senders node id The interface subcomponent Position Control Verify at Reset Position Value 10 [0, 127] [0, 127] [0, 255] 0x07 0x05

Response: Reply Verify Reset Reply

Verify Reset Reply (0x06)

This interface returns the status of the device re the reset position. The device can be at the reset position or not at the reset position, or there may have been an error achieving the reset position. For example, if there could be a mechanical blockage that keeps the device from achieving the reset position so that the motor goes into current overload, or there could be a problem with the reset position indicator device. Byte 1 2 3 4 5-6 7 8 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Status Description The length of the packet The responding nodes id The senders node id The interface subcomponent Position Control Verify Reset Reply Reset Position Status Value 11 [0, 127] [0, 127] [0, 255] 0x07 0x06 Character: Status (see below)

Response: none Possible status replies are: T - at reset position; F not at reset position; E error when trying to achieve reset position.

Get Position (0x07)

Byte Name 1 Length (in bytes) 2 Destination node 3 Source node 4 Subcomponent 5-6 Interface 7 Method Response: Return Position Description The length of the packet The responding nodes id The senders node id The interface subcomponent Position Control Get Position Value 10 [0, 127] [0, 127] [0, 255] 0x07 0x07

Page 31

Inuktun Services Ltd.

ER-SP-I0013-09

October 21, 2013

Return Position (0x08)

Byte Name 1 Length (in bytes) 2 Destination node 3 Source node 4 Subcomponent 5-6 Interface 7 Method 8-11 Count Response: none Description The length of the packet The responding nodes id The senders node id The interface subcomponent Position Control Return Position The current encoder count Value 14 [0, 127] [0, 127] [0, 255] 0x07 0x08 Int32 [0..Maximum]

Set Parameters (0x09)

This command sets critical parameters: the maximum encoder count allowable for the device, and the maximum speed at which the motor should turn when changing position. The maximum speed is set as a single byte between 1 and 255, where 255 is equivalent to the fastest speed the motor can achieve; therefore a value of 128 for the speed would be equivalent to half speed. After setting the parameters (they should be stored in non-volatile storage on the device), the device should respond with the Set Parameters Response. Byte Name Description 1 Length (in bytes) The length of the packet 2 Destination node The responding nodes id 3 Source node The senders node id 4 Subcomponent The interface subcomponent 5-6 Interface Position Control 7 Method Set Parameters 8-11 Maximum The maximum encoder count 12 Speed The maximum speed to use Response: Set Parameters response Value 15 [0, 127] [0, 127] [0, 255] 0x07 0x09 Int32 [0..Maximum] Uint8[1..255]

Set Parameters Response (0x0a)

Byte Name 1 Length (in bytes) 2 Destination node 3 Source node 4 Subcomponent 5-6 Interface 7 Method Response: none Description The length of the packet The responding nodes id The senders node id The interface subcomponent Position Control Set Parameters Response Value 10 [0, 127] [0, 127] [0, 255] 0x07 0x0a

Stop (0x0b)
This command will stop the motor. Byte Name 1 Length (in bytes) 2 Destination node 3 Source node 4 Subcomponent 5-6 Interface 7 Method Response: none Description The length of the packet The responding nodes id The senders node id The interface subcomponent Position Control Stop Value 10 [0, 127] [0, 127] [0, 255] 0x07 0x0b

Page 32

Inuktun Services Ltd.

ER-SP-I0013-09

October 21, 2013

Set Speed Position Control (0x0c)

This command requests the device to move to a specified position with a speed control, expressed as an encoder count. Depending on the difference between the current position and the new one, this movement could take some time. Byte 1 2 3 4 5-6 7 8-11 12-15 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Position Desired Speed Description The length of the packet The responding nodes id The senders node id The interface subcomponent Position Control Set Speed Position Control The desired position encoder count Desired speed Value 18 [0, 127] [0, 127] [0, 255] 0x07 0x0c Int32 [0..Maximum] 0-Maximum(float)

Response: Set Position Reply

Speed Position Control Reply (0x0d)

This packet returns the current encoder count and up to two feedback parameters. The number of bytes returned by this reply will depend on whether 0, 1 or 2 feedback parameters have been specified in the Return Position Control Parameter Info packet. Byte 1 2 3 4 5-6 7 8-11 12-15 16-19 20-23 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Position Current speed Feedback parameter 1 Feedback parameter 2 Description The length of the packet The responding nodes id The senders node id The interface subcomponent Position Control Speed Position Control Reply Current encoder counts Feedback parameter 1 value (optional) Feedback parameter 2 value (optional) Value 18, 22 or 26 [0, 127] [0, 127] [0, 255] 0x07 0x0d Int32 [0..Maximum] Float Float Float

Response: none

Zero Position (0x0e)

Byte 1 2 3 4 5-6 7 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Description The length of the packet The responding nodes id The senders node id The interface subcomponent Position Control Set Speed Position Control Value 10 [0, 127] [0, 127] [0, 255] 0x07 0x0e

Response: Zero Position Reply

Page 33

Inuktun Services Ltd.

ER-SP-I0013-09

October 21, 2013

Zero Position Reply(0x0f)

Byte 1 2 3 4 5-6 7 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Description The length of the packet The responding nodes id The senders node id The interface subcomponent Position Control Set Speed Position Control Value 10 [0, 127] [0, 127] [0, 255] 0x07 0x0f

Response: None

Auxiliary Control Interface (0x08)

This interface is used to control auxiliary components that are included in a device. The interface has two methods, described below. The Auxiliary Control Set command tells the component what it should do, and the device responds with the Auxiliary Control Reply packet containing the value of two optional feedback parameters.

Arm Raise Control Set (0x00)

Byte 1 2 3 4 5-6 7 8 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Control byte Description The length of the packet The responding nodes id The senders node id The interface subcomponent Auxiliary control Arm Raise control set 0: No power 1: Power higher 2: Power lower 3: Get status Value 11 [0, 127] [0, 127] [0, 255] 0x08 0x00 UInt8

Response: Arm Raise Control Reply

Page 34

Inuktun Services Ltd.

ER-SP-I0013-09

October 21, 2013

Arm Raise Control Reply (0x01)

Byte 1 2 3 4 5-6 7 8 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Control status Description The length of the packet The responding nodes id The senders node id The interface subcomponent Auxiliary control Auxiliary control reply Raise arm 0: No power 1: Raising 2: Holding raise position 3: Lowering 4: Holding lower position. 5: Calibrating Value 19 [0, 127] [0, 127] [0, 255] 0x08 0x01 Uint8

9-12

Position (degrees) Pressure (psi)

Arm position

Float Degrees Float Psi

13-16

Touch pressure

Arm Raise Calibration Set (0x02)

Byte 1 2 3 4 5-6 7 8 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Control byte Description The length of the packet The responding nodes id The senders node id The interface subcomponent Auxiliary control Arm Raise calibration set 0: Get status 1: Start calibration 2: Exit calibration Value 11 [0, 127] [0, 127] [0, 255] 0x08 0x02 UInt8

Response: Arm Raise Calibration Reply

Page 35

Inuktun Services Ltd.

ER-SP-I0013-09

October 21, 2013

Arm Raise Calibration Reply (0x03)

Byte 1 2 3 4 5-6 7 8 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Control status Description The length of the packet The responding nodes id The senders node id The interface subcomponent Auxiliary control Auxiliary control reply 0: No calibration 1: Calibrating 2: Complete 3: Fault Value 11 [0, 127] [0, 127] [0, 255] 0x08 0x03 Uint8

Lights Control Interface (0x09)

Set Light Control (0x00)
Byte 1 2 3 4 5-6 7 8-11 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Light set point Description The length of the packet The responding nodes id The senders node id The interface subcomponent Lights Control Interface Set Light Control The desired light set point. Value 14 [0, 127] [0, 127] [0, 255] 0x09 0x00 Float [Minimum, Maximum]

Response: Light Control Reply

Light Control Reply (0x01)

Byte 1 2 3 4 5-6 7 8-11 12-15 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Feedback parameter 1 Feedback parameter 2 Description The length of the packet The responding nodes id The senders node id The interface subcomponent Lights Control Interface Light Control Reply Light current Feedback parameter 1 value (optional) Value 10, 14 or 18 [0, 127] [0, 127] [0, 255] 0x09 0x01 Float Float

Response: none

Page 36

Inuktun Services Ltd.

ER-SP-I0013-09

October 21, 2013

Get Light Parameter Info (0x02)

Byte 1 2 3 4 5-6 7 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Description The length of the packet The responding nodes id The senders node id The interface subcomponent Lights Control Interface Get Light Parameter Info Value 10 [0, 127] [0, 127] [0, 255] 0x09 0x02

Response: Return Lights Parameter Info

Return Lights Parameter Info (0x03)

Byte 1 2 3 4 5-6 7 8-11 12-15 16 17 18 Name Length (in bytes) Destination node Source node Subcomponent Interface Method Maximum Minimum Light type Parameter 1 Parameter 2 Description The length of the packet The responding nodes id The senders node id The interface subcomponent Lights Control Interface Return Lights Parameter Info The maximum light setpoint(A) The minimum light setpoint(A) Feedback parameter 1 type Feedback parameter 2 type Value 21 [0, 127] [0, 127] [0, 255] 0x09 0x03 Float Float 0: 801 V or A or X if not present V or A or X if not present

Response: none

Error Interface (0xFF)

This interface exists to facilitate error handling and debugging. In place of any response, a node may transmit an error or exception. The intention is that, if a language having exception handling has been used to implement the controller, the exception message may be used to generate a bona fide exception in the controller, and aid root-cause analysis. The Error interface currently contains methods corresponding to the following runtime exceptions and errors: OutOfMemoryError - 1 UnknownError - 2 ArrayIndexOutOfBoundsException - 3 IllegalArgumentException - 4 IllegalStateException - 5

as well as a single non-runtime exception: IOException - 6

0 is reserved for errors/exceptions that havent been added to this list, and would result in a generic Throwable. This list may be extended by future revisions of this document, but for the moment, it is the short list of what would appear to be immediately useful.

Page 37

Inuktun Services Ltd.

ER-SP-I0013-09

October 21, 2013

Throw (0x00)
Byte 1 2 3 4-5 6 7 8 Name Length (in bytes) Destination node Source node Interface Method Throwable ID Message Description The length of the packet The responding nodes id The senders node id Error Throw The ID of the throwable An array of 8-bit ASCII characters containing the intended message (or key to the internationalized version) for the exception Value 15 [0, 127] [0, 127] 0x01 0x00 Currently [0, 6] [0, 245], but packets must be kept to within the size of the devices buffer

Response: None

Implementation note: Should the controller software be written in an exception-capable language, it remains necessary to map errors/exception from the serial protocol into those of the controllers implementation lan guage. The errors and exceptions included thus far have a 1:1 mapping in the Java language. One will further notice that, in Java, all the exceptions used here (except IOException) inherit from RuntimeException, meaning that they do not have to be declared. As any method may return one of these Throwables in place of the expected response, inclusion of a non-Runtime exception dictates that all controller methods receiving a response via this serial protocol would need to declare that exception. Clearly, inclusion of such exceptions in this interface should not be done without careful consideration. It is intended that the controller have a getResponse(), or some such method, by which the code necessary to turn serial protocol exceptions into those of the implementation language will exist in only one place.

Various Comments, Notes, Things to Do

Would like to be able to identify 2XL controllers as L / R - metadata? - 1 byte metaID - How do I dictate which is the master? - go by node ID? metaID - Dont call it metaID, call it controller position, or something. (Internal method) The one with the lowest position is the master. What about failure?

- How big to make packet buffer

- Light, Sony FCB-blah, Open loop p/t, Position mode p/t, Transporter velocity control

- Group configuration - enumerate

Watchdog is at node level (still on the bus, and is being sent commands) - think about tracks, though Make node watchdog commands part of an interface E-stop

Page 38

Inuktun Services Ltd.

ER-SP-I0013-09

October 21, 2013

In EE-PROM: = 10 - MAC address (4) - S/N (4) - Node ID (1) - Meta ID Each composite registration: 6

Page 39