131021_inuktunprotocol.pdf

8/13/2019 131021_InuktunProtocol.pdf

1/43

Inuktun Services Ltd. ER-SP-I0013-09 October 21, 2013

Page i

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 .................................................................................................................................................. 1Signaling rates ........................................................................................................................................... 1Timing Constraints ..................................................................................................................................... 1Coordinate System Definition .................................................................................................................... 1Byte Ordering ............................................................................................................................................ 2Definitions .................................................................................................................................................. 2Philosophical Differences .......................................................................................................................... 2

Encapsulation ........................................................................................................................................ 2Example: ................................................................................................................................................ 3Real-World Units .................................................................................................................................... 3Example: ................................................................................................................................................ 3

Packet Structure ........................................................................................................................................ 4Standard packets ................................................................................................................................... 4Group control packets ............................................................................................................................ 5

CRC Calculation ........................................................................................................................................ 5The Interfaces ............................................................................................................................................... 6

Summary of the Interfaces ........................................................................................................................ 6Administrative Interface (0x00) .................................................................................................................. 7Identification .............................................................................................................................................. 7

Identify device configure (0x00) ............................................................................................................. 7Identify Node ID configure (0x01) .......................................................................................................... 8Ping (0x02) ............................................................................................................................................. 8

Ping Reply (0x03) .................................................................................................................................. 8

Identify and interrogate .............................................................................................................................. 9Identify (0x04) ........................................................................................................................................ 9

Determining Supported Interfaces ............................................................................................................. 9Enumerate supported interfaces (0x05) ................................................................................................ 9Supported interfaces response (0x06)................................................................................................. 10


2/43


Page ii

Composite Packet Definition ................................................................................................................... 10Subscribe to composite packet (0x07) ................................................................................................. 11Unsubscribe from composite packet (0x08) ........................................................................................ 12Remove all composite packet subscriptions (0x09) ............................................................................ 12 Composite packet subscription response (0x0a) ................................................................................. 12Enumerate composite packet subscriptions (0x0b) ............................................................................. 13Report composite packet subscriptions (0x0e) .................................................................................... 13Firmware Version Request (0x0f) ........................................................................................................ 14Firmware Version Reply (0x10) ........................................................................................................... 14

Environmental Parameter Interface (0x01) ............................................................................................. 15Get Environmental Parameters (0x00) ................................................................................................ 15Return Environmental Parameters (0x01) ........................................................................................... 16Get Available Parameters (0x02) ......................................................................................................... 16Return Available Parameters (0x03) .................................................................................................... 16Set Zero Offsets (0x04)........................................................................................................................ 17

Amplitude Control Interface (0x02) .......................................................................................................... 18Set Amplitude (0x00) ........................................................................................................................... 18Amplitude Reply (0x01)........................................................................................................................ 18Get Amplitude Control Parameter Info (0x02) ..................................................................................... 18Return Amplitude Control Parameter Info (0x03) ................................................................................ 19

Closed Loop Rotating Machine Linear Motion Control Interface (0x03) ................................................. 20Set Speed (0x00) ................................................................................................................................. 20Set Speed Reply (0x01) ....................................................................................................................... 20Get Closed Loop Rotating Machine Parameter Info (0x02)................................................................. 21 Return Closed Loop Rotating Machine Parameter Info (0x03)............................................................ 21Set Raw Position (0x08) ...................................................................................................................... 21Set Raw Position Reply (0x09) ......................................................................................................... 22

iGEMS Gamma Radiation Detector Interface (0x04) .............................................................................. 23Get number of events in FIFO (0x04) .................................................................................................. 23Return number of events in FIFO (0x84) ............................................................................................. 23Success response (0xFE) .................................................................................................................... 23Failure response (0xFF)....................................................................................................................... 24Clear event FIFO (0x05) ...................................................................................................................... 24Get iGEM unit number (0x0B) ............................................................................................................. 24Return iGEM Unit Number (0x8B) ....................................................................................................... 24Get detector type (0x0D) ..................................................................................................................... 25Return iGEM Detector Type (0x8D)..................................................................................................... 25


3/43


Page iii

Get detector bias voltage (0x0F) ......................................................................................................... 25Return detector bias voltage (0x8F) .................................................................................................... 25Set ASIC Gain (0x10) .......................................................................................................................... 26Set ASIC Shaping Time (0x11) ............................................................................................................ 26Set High Voltage Level (0x12) ............................................................................................................. 26Set FIFO Nearly Full Value (0x13) ....................................................................................................... 27Enable/Disable Event Counter (0x14) ................................................................................................. 27Read and Reset Event Counter (0x15)................................................................................................ 27Return Event Count (0x95) .................................................................................................................. 28Get N Events (0x40) ............................................................................................................................ 28Return N Events (0xC0) ....................................................................................................................... 28

Rotating Motor Position Control Interface (0x07) .................................................................................... 29 Set Position (0x00) ............................................................................................................................... 29Set Position Reply (0x01) .................................................................................................................... 29Get Position Control Parameter Info (0x02)......................................................................................... 30Return Position Control Parameter Info (0x03) ................................................................................... 30 Move to Reset Position (0x04) ............................................................................................................. 30Verify at Reset Position (0x05) ............................................................................................................ 31Verify Reset Reply (0x06) .................................................................................................................... 31Get Position (0x07) .............................................................................................................................. 31Return Position (0x08) ......................................................................................................................... 32Set Parameters (0x09) ......................................................................................................................... 32Set Parameters Response (0x0a) ....................................................................................................... 32Stop (0x0b) .......................................................................................................................................... 32Set Speed Position Control (0x0c) ....................................................................................................... 33Speed Position Control Reply (0x0d) ................................................................................................... 33Zero Position (0x0e) ............................................................................................................................. 33Zero Position Reply(0x0f) ................................................................................................................. 34

Auxiliary Control Interface (0x08) ............................................................................................................ 34Arm Raise Control Set (0x00) .............................................................................................................. 34Arm Raise Control Reply (0x01) .......................................................................................................... 35Arm Raise Calibration Set (0x02) ..................................................................................................... 35Arm Raise Calibration Reply (0x03)................................................................................................. 36

Lights Control Interface (0x09) ................................................................................................................ 36Set Light Control (0x00) ....................................................................................................................... 36Light Control Reply (0x01) ................................................................................................................... 36Get Light Parameter Info (0x02) .......................................................................................................... 37


4/43


Page iv

Return Lights Parameter Info (0x03) ................................................................................................... 37Error Interface (0xFF) .............................................................................................................................. 37

Throw (0x00) ........................................................................................................................................ 38Various Comments, Notes, Things to Do .................................................................................................... 38


5/43


Page 1

The Protocol

This protocol is an adaptation of the serial protocol described in ER-SP-I0011-01. It extends the oldprotocol to handle the following:

Addressing same-type components: with the old protocol, it was not possible to have two of thesame 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 whichcomponents are enumerated. Allowing this to happen at run-time makes it possible to have "plugand play" components.

Run-time formation of ad-hoc groups: allows arbitrary groups of components (all forward-facinglights, 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 thereis nothing to prevent using multiple controllers, so long as they coordinate between themselves to avoidbus 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 a2-byte CRC. The maximum packet length is 255 bytes. Data flow is governed by the controller/host. Allother components will transmit only if they have received a valid packet directed at them.

Signal ing rates

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

Timing Const ra ints

Name Min(ms)

Typical(ms)

Max(ms)

Description

Reply PacketLatency

10 The time between a host request and a slavereply

Host PacketPeriod

75 The time between the host sending requestsunder normal conditions

Receive PacketTimeout

100 The time after which the host mayassume apacket loss after sending a request and waitingfor a reply

Receive ByteTimeout

30 The time after which the host may assume anincomplete packet and attempt to send a newone

Coord inate System Def ini t ion

By definition,xextends from the front of the component, yextends to the right, and zextends from thebottom. So, for example, giving an ROV a command of [+1, -1, +1] would cause it to move forward and tothe left, while diving.

Rationale:xextending from the front of the vehicle aligns the nose of a vehicle with its heading. Further,heading angle increases when turning clockwise, so ymust be to the right. While it may seem moreintuitive for zto extend up, rather than down, this would break the right hand rule. Adherence to the righthand rule is important so that coordinate transforms can be performed via matrix multiplication.


6/43


Page 2

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

Byte Order ing

On-the-wire byte ordering shall follow network byte ordering convention. In other words, all data typesshould be transmitted most significant byte first. In C, htonand ntohfunctions provide this mapping.

Defini t ions

The following definitions are for a device, which can be assumed to be a microcontroller that is incommunication with a controller on the RS-485 bus.

Node id(bytetype) 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 id255, which signifies that it has not yet been assigned a proper node id. Given the limitations of RS-485signaling, allowing a larger range (thus demanding a larger data type) would probably produce littlebenefit. 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 anon-volatile, semi-permanent id for a particular component. It is intended to be set during production, andprovides a means to discriminate between components that are grouped together into something that isgiven a serial number. Thus, a Minitrac-2XL might have a single serial number, but it would have twomotor drivers, each with their own physical address. Unlike in Ethernet, this is not used for routing, butsolely for bootstrapping to the point that the device can be given a Node id. Each and everymicrocontrolled device manufactured by Inuktun should have a uniquemachine address.

Serial number(UInt32 type) This is the standard Inuktun serial number that is given to a device. It isnot necessarily unique, because it is in theory possible that a product made by Inuktun with a single serialnumber may include more than one device, each of which will have the same serial number but differentmachine addresses.

Group(bytetype) A plurality of nodes that, for some reason, is convenient to treat collectively. Groupids are used in place of Node ids, and can have the range [128, 255]. The node id 255 is defined to bethe broadcast / all nodes group.

Interface(UInt16type) A collection of methods supported by a component. A component may supportmore than one interface.

Subcomponent(bytetype) This index is used to identify components within a single device thatimplement the same interface. For example a single device may control two banks of lights each of whichis independent of the other. Most interfaces will only be implemented by the root subcomponent, which iszero.

Method(bytetype) These describe the methods provided by the interface.

Phi loso ph ical Dif ferences

Encapsulation

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


7/43


Page 3

Example:

A Spectrum 90 is actually a pan/tilt gimbal, camera, light source, and possibly laser striper all rolled intoone. So, under this paradigm, it would implement at least three separate interfaces. A forward-viewingcamera would be similar, but simply not implement pan/tilt. Now, assume Sony develops another camerablock 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 wouldneed to be adapted, and, provided that the addi tional features were purely an extension of the blocksfeatures, the camera could simultaneously implement both the old and new interfaces for the camerablock.

Notice that this also provides a mechanism to address options. If the particular SP90 has lasers, then itwill 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 quantitysnatural representation may not be a whole number. The jump to floating point has its drawbacks, mostnotably 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 singlebyte, with +127 meaning full forward, and -127 meaning full reverse. Thus, the resolution (and unit ofmeasurement) is 1/127

thof 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 areto look to the same command for their speed, they must use a shared representation. Taking this onestep 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 interms of candela, for instance. The number isnt likely to have meaning for the operator, and a group oflights commanded to do the same thing probably shouldbe commanded as a fraction of their full

intensity.


8/43


Page 4

Packet Structure

Standard packets

All packets except group control packets must have the following structure:

Byte Name Description Value0 Start byte All packets begin with this value.

It serves as a marker, and helpsto synchronize UARTs with autobaud rate detection

0xAA

1 Length (in bytes) The length of the packet(including start byte and CRCs),in bytes

[10, 255]. Each node shall be ableto cope with packets havinglengths up to 255 being presenton the bus, but the size of anodes receive buffer may dictatethat it is not able to itself receivesuch a large packet. 32 or 64would be a much more practical

expectation.2 Destination node The node id or group id of the

receiver(s)Group or node id; [0, 255]

3 Source node The senders node id Node id; [0, 127]

4 Subcomponent The subcomponent (within thenode) that is being addressed

[0, 255]

5-6 Interface /Component

The interface upon which themethod is being called

[0, 65535]

7 Method The number of the method withinthe interface

[0, 255]

[8, 8+n) Data The parameters of the method Byte array with arbitrary contents,having length, n,in the range [0,245]

8+n CRCH The most significant byte of theCRC.

[0, 255]

9+n CRCL The least significant byte of theCRC.

[0, 255]


9/43


Page 5

Group control packets

Group control packets must have the following structure:

Byte Name Description Value

0 Start byte All packets begin with this value.It serves as a marker, and helps

to synchronize UARTs with autobaud rate detection

0xAA

1 Length (in bytes) The length of the packet(including start byte and CRCs),in bytes

[10, 255]. Each group shall beable to cope with packets havinglengths up to 255 being presenton the bus, but the size of anodes receive buffer may dictatethat it is not able to itself receivesuch a large packet. 32 or 64would be a much more practicalexpectation.

2 Destination node The group id of the receiver(s) Group id; [128, 254]

3 Source node The senders node id Node id; [0, 127]

4 Response Index [0, 250][5, 5+n) Data Parameters of the method used

by the group, possibly for eachnode in the group.

Byte array with arbitrary contents,having length, n,in the range [0,245]

8+n CRCH The most significant byte of theCRC.

[0, 255]

9+n CRCL The least significant byte of theCRC.

[0, 255]

CRC Calculat ion

The CRC is calculated using the polynomial X^16 + X^12 + X^5 + 1. To calculate the CRC, use thefollowing 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 notbe included in the CRC calculation (how could they be?).

Implementat ion 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, thecontroller will timeout, and retransmit if necessary.


10/43


Page 6

The Interfaces

Summary of the Interfaces

Interface Name Number

(hex)

Number

of MethodsAdministrative 00 16

Environmental Parameter 01 5

Amplitude Control 02 4

Closed Loop Rotating Machine Linear Motion 03 4

IGEMS Gamma Radiation Detector 04 20

Position Control 07 11

Error FF 1

Table 1: Summary of the Interfaces


11/43


Page 7

Adm inis trat ive Interface (0x00)

Under this protocol, there are a number of administrative functions that every node must be able toperform. 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 berequired to actually use a newly-inserted component, the system shall be able to detect and communicatewith the component with no operator intervention beyond instructing the system to scan for newcomponents. To ensure that all devices will be discovered, devices must implement some means ofavoiding 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: Camera1: Track(AF)2: Telemetry can(BH)3: Traction enhancement

Identify device configure (0x00)


1 Length (in bytes) The length of the packet 22

2 Destination node The responding nodes id [0, 127] or 2553 Source node The senders node id [0, 127]

4 Subcomponent The root subcomponent 0

5-6 Interface Administrative 0x00

7 Method Identify device configure 0x00

8-11 Serial number The serial number of the piece ofequipment containing the node

[1, 2147483648]

12-15 New Physicaladdress

The physical address of thenode

[1, 2147483648]

16-19 New Serialnumber

The serial number of the piece ofequipment containing the node

[1, 2147483648]

Response: None

Upon reception of a Identify device configurepacket, the device will update its physical address andserial number to those provided only when packet serial number=0xffffffff or device serial number is equalto the packet serial number.

This packet could be used in production to save a serial number and machine address to a device.


12/43


Page 8

Identify Node ID configure (0x01)



2 Destination node The responding nodes id [0, 127] or 2553 Source node The senders node id [0, 127]



7 Method Identify Node ID configure(extended ack)

0x01


[1, 2147483648]

12 New node id A new node id that theresponding node should assumeupon packet reception

[0, 127]

Response:None

Upon reception of a Identify Node ID configurepacket, the node shall immediately assume the newnode ID and consider the discovery process successful only when packet serial number=0xffffffff ordevice serial number is equal to the packet serial number.

Ping (0x02)



2 Destination node The responding nodes id [1, 127] ,255

3 Source node The senders node id [1, 127]



7 Method Ping 0x028-11 Serial number The serial number of the piece of

equipment containing the node[0, 255]

Response:Ping Reply

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

Ping Reply (0x03)



2 Destination node The responding nodes id [0, 127]


4 Subcomponent The root subcomponent 05-6 Interface Administrative 0x00

7 Method Ping Reply 0x03

8-11 Physicaladdress

The physical address of thenode

[1, 2147483648]


[1, 2147483648]

Response:none


13/43


Page 9

Identify and interrogate

Identify (0x04)



2 Destination node The responding nodes id [0, 127]3 Source node The senders node id [0, 127]



7 Method Identify 0x04

8 ID number /on/off

A number that the node shouldtry to convey to the user

[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 idnumberis non-zero, the node shall attempt to identify itself by some means native to it. If its a lightsource, it might flash, for example. Optionally, the device may try to convey the number, by flashing inbursts of long and short flashes, for example.

Determining Supported Interfaces

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

Enumerate supported interfaces (0x05)







7 Method Enumerate supported interfaces 0x05

8 Page The page of interfaces therequester is interested in

[0, 255]

Response:Supported interfaces response

Recalling that packets can have a maximum length of 255 bytes, and many components may use bufferssubstantially 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 ncan vary between 1 and 122) interfacesthe component should reply.


14/43


Page 10

Supported interfaces response (0x06)


1 Length (in bytes) The length of the packet 13+



4 Subcomponent The root subcomponent 05-6 Interface Administrative 0x00

7 Method Supported interfaces response 0x06

8 Last page Is this that last page ofinterfaces

0not last page1last page

9-10 Interface 0 The first supported interface [1, 65535]

11 Subcomponent 0 The subcomponent of the firstsupported interface

[0,255]

12-13 Interface 1 The second supported interface [1, 65535]

14 Subcomponent 1 The subcomponent of thesecond supported interface

[0,255]

Response:NoneImplementat ion note:

Support for the administrative interface (0x00) is assumed, and need not be included. The Supportedinterfacespacket, like all others, must include a two-byte CRC.

Composite Packet Definition

A key difference between this protocol and those that have preceded it is that this one is extensible at runtime. In this way, components can be assembled together to create custom systems, without having tomodify 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 asystem 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 bycommunicating 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 isntparticularly important in the case of controlling lights, but it can make a difference for components wheremotion is involved.

In addition to simple grouping, this mechanism can be used to allow stock components to be used in anumber of different systems without having to reprogram them. In this way, both a microcontrolled VT150and a Hydra

1system 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.

1In 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 formiles.


15/43


Page 11

Subscribe to composite packet (0x07)






[0, 255]


7 Method Subscribe to composite packet 0x07

8 Group The composite node that willover which this packet hasinfluence

[128, 254]

9 Packet index The index of the start of theparameters of the nativecommand within the compositepacket

[0, 250], but packets must be keptto within the size of the devicesreceive buffer

10-11 Native interface The interface of the nativecommand

[0, 65535]

12 Native method The method of the nativecommand

[0, 255]

13 Response index The number of response packetsthat should occur before thenode should respond

[0, 255], but realistically probablyno more than 10. 255 signifies donot respond.

Response:Composite packet subscription response

Upon reception of a Subscribe to composite packet, the component shall react to incoming packetswith the subscribed group. When such a packet is received, the component will interpret the data atpacket indexas a command having interface native interfaceand method native method. Shouldresponse indexbe less than 255, the component will reply to the commanded packet after responseindexother components have already done so. In this way, any subset of the components subscribed tothe composite command can be made to respond, in turn.

Trivial grouping would be implemented by having multiple components look to the same packet index fortheir command.

It is intended that components persist their subscriptions between power interruptions, presumably bywriting them into EE-PROM. This would require 6 bytes per subscription.


16/43


Page 12

Unsubscribe from composite packet (0x08)






[0, 255]


7 Method Unsubscribe from compositepacket

0x08

8 Group The composite node that willover which this packet hasinfluence

[128, 254]

9 Packet index The index of the start of thenative command within thecomposite packet



Upon reception of an Unsubscribe from composite packetpacket, the component shall no longer lookto packet indexupon an incoming packet with the subscribed group. Note that a component may bemade to subscribe to the same group multiple times, so as to react to multiple commands embedded inthe composite packet. The correct behavior for an unsubscribecommand is to remove only thesubscription looking to packet index, and not to remove all subscriptions of the particular group.

Remove all composite packet subscriptions (0x09)






[0, 255]


7 Method Remove all composite packetsubscriptions

0x09


Composite packet subscription response (0x0a)






[0, 255]


7 Method Composite packet subscriptionresponse

0x0a

8 Return code Was the component able tosubscribe to the compositecommand

0x00 = success, otherwise failure

Response:None


17/43


Page 13

Enumerate composite packet subscriptions (0x0b)






[0, 255]


7 Method Enumerate composite packetsubscriptions

0x0b

8 Page The page of subscriptions therequester is interested in

[0, 255]

Response:Composite packet subscriptions

Report composite packet subscriptions (0x0e)


1 Length (in bytes) The length of the packet 16+



6 Method Report composite packetsubscriptions

0x0e

7 Last page Is this that last page of interfaces 0not last page1last page

8 Group1 The composite node that willover which this packet hasinfluence

[128, 254]

9 Packet index1 The index of the start of thenative command within thecomposite packet


10-11 Native interface1 The interface of the nativecommand

[0, 65535]

12 Native method1 The method of the nativecommand

[0, 255]

13 Responseindex1

The number of response packetsthat should occur before thenode should respond


14 Group2 The composite node that willover which this packet hasinfluence

[128, 254]

15 Packet index2 The index of the start of thenative command within thecomposite packet


16-17 Native interface2 The interface of the nativecommand

[0, 65535]

18 Native method2 The method of the nativecommand

[0, 255]

19 Responseindex2

The number of response packetsthat should occur before thenode should respond


Response:None


18/43


Page 14

Firmware Version Request (0x0f)







7 Method Firmware Version Request 0x0f

Response:Firmware Version Reply

Firmware Version Reply (0x10)







7 Method Ping Reply 0x10

8 Version Number [0, 255]


19/43


Page 15

Env ironmental Parameter Interface (0x01)

This interface is used to get information from various sensors that are included in a device, but are notfeedback parameters from other interfaces. Up to 16 parameters can be returned at once, always asfloats 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 Parameter Unit

0 Temperature Celsius Degrees

1 Humidity Percent Relative Humidity

2 Voltage input Volts

3 Voltage output Volts

4 Current Input Amperes

5 Current Output Amperes

6 Pitch Degrees

7 Roll Degrees

8 Gyro X Rate Degrees/sec

9 Gyro Y Rate Degrees/sec

10 Gyro Z Rate Degrees/sec

11 Gas concentration Percent full-scale

12 Depth Meters

13 Flow speed Meters/second

14 Power State 00:Normal,01:DC1 Fault.02:DC2 Fault.03:DC1 and DC2 Fault.

15 Position Sensor Encoder Counts

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

Get Environmental Parameters (0x00)





4 Subcomponent The interface subcomponent [0, 255]

5-6 Interface Environmental ParameterInterface

0x01

7 Method Get Parameters 0x00

8-9 Parameter Mask Bit mask showing theparameters to return.

UInt16 [1, 65535]

Response: Return Environmental Parameters


20/43


Page 16

Return Environmental Parameters (0x01)


1 Length (in bytes) The length of the packet 10 + 4 * n



4 Subcomponent The interface subcomponent [0, 255]5-6 Interface Environmental Parameter

Interface0x01

7 Method Get Parameters Reply 0x01

8-11 Parameter 1 Parameter corresponding tolowest nonzero bit value

Float

12-15 Parameter 2 Parameter corresponding to nextlowest nonzero bit value

Float

Parameter n Parameter corresponding to lastbit value

Float

Response: none

Get Available Parameters (0x02)







0x01

7 Method Get Available Parameters 0x02

Response: Return Available Parameters

Return Available Parameters (0x03)







0x01

7 Method Return Available Parameters 0x03

8-9 Parameter Mask Bit mask showing the availableparameters

UInt16 [1, 65535]

Response: none


21/43


Page 17

Set Zero Offsets (0x04)






Interface0x01

7 Method Set Zero Offsets 0x04

8-9 Parameter Mask Bit mask showing theparameters to set offsets for.

UInt16 [1, 65535]

Response: None

Set Motor Torque Limit (0x0c)Byte Name Description Value






0x01

7 Method Set Motor Torque Limit 0x0c

8 Torque limit 0-100

Response: Motor Torque Limit Reply

Read Motor Torque Limit (0x0d)Byte Name Description Value





Interface0x01

7 Method Read Motor Torque Limit 0x0d

Response: Motor Torque Limit Reply

Motor Torque Limit Reply (0x0e)Byte Name Description Value





5-6 Interface Environmental ParameterInterface 0x01

7 Method Motor Torque Limit Reply 0x0e

8 Torque limit 0-100

Response: none


22/43


Page 18

Am pl i tud e Contro l Interface (0x02)

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

Set Amplitude (0x00)




3 Source node The senders node id [0, 127]4 Subcomponent The interface subcomponent [0, 255]

5-6 Interface Amplitude Control 0x02

7 Method Set Amplitude 0x00

8-11 Amplitude The desired amplitude Float [Minimum, Maximum]

Response: Amplitude Reply

Amplitude Reply (0x01)


1 Length (in bytes) The length of the packet 10, 14 or 18



4 Subcomponent The interface subcomponent [0, 255]5-6 Interface Amplitude Control 0x02

7 Method Set Amplitude Reply 0x01

8-11 Feedbackparameter 1

Feedback parameter 1 value(optional)

Float



Float

Response: none

Get Amplitude Control Parameter Info (0x02)





5-6 Interface Amplitude Control 0x02


Response: Return Amplitude Control Parameter Info


23/43


Page 19

Return Amplitude Control Parameter Info (0x03)





4 Subcomponent The interface subcomponent [0, 255]5-6 Interface Amplitude Control 0x02

7 Method Return Parameters 0x03

8-11 Maximum The maximum value in effect Float [-1.0, 1.0]

12-15 Minimum The minimum value in effect Float [-1.0, 1.0]

16 Interface type The type of device beingcontrolled

See below for codes

17 Parameter 1type

Feedback parameter 1 type V or A or X if not present

18 Parameter 2type

Feedback parameter 2 type V or A or X if not present

Response: none

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


24/43


Page 20

Closed Loop Rotat ing Mach ine Linear Mot ion Contro l Interface (0x03)

This interface is for controlling a linear motion device driven by a rotating machine such as an electricmotor. It is assumed that the rotating machine includes an encoder that counts the rotations of themachine in some way such that the absolute speed of the device can be known and controlled. Theinterface 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 andmaximum must be in real-world units of meters per second, and the maximum must be greater than theminimum. The Set Speedcommand tells the device how fast to go and in which direction (if the devicehas the capacity for bidirectional motion), and the device responds with the Set Speed Replypacketcontaining information about the current state of the rotating machine and the value of two optionalfeedback parameters. These feedback parameters can be either voltage (Volts) or current (Amperes).The Get Closed Loop Rotating Machine Parameter Infopacket asks the device to respond with theReturn Closed Loop Rotating Machine Parameter Infopacket, containing the maximum and minimumspeeds in effect for the device, calibration information for the encoder, and the definition of the optionalfeedback parameter types.

Set Speed (0x00)


1 Length (in bytes) The length of the packet 142 Destination node The responding nodes id [0, 127]



5-6 Interface Closed Loop Rotating MachineLinear Motion Control Interface

0x03

7 Method Set Speed 0x00

8-11 Speed The desired speed (meters/sec) Float [Minimum, Maximum]

Response: Set Speed Reply

Set Speed Reply (0x01)


1 Length (in bytes) The length of the packet 18, 22 or 262 Destination node The responding nodes id [0, 127]




0x03

7 Method Set Speed Reply 0x01

8-11 Speed Track speed(Meters /Min) Positive or negative Float

12-15 Total_Counts Cumulative encoder counts UInt32



Float


Feedback parameter 1 value(optional

Float

Response: none


25/43


Page 21

Get Closed Loop Rotating Machine Parameter Info (0x02)





4 Subcomponent The interface subcomponent [0, 255]5-6 Interface Closed Loop Rotating Machine

Linear Motion Control Interface0x03


Response: Return Closed Loop Rotating MachineParameter Info

Return Closed Loop Rotating Machine Parameter Info (0x03)







0x03

7 Method Return Parameters 0x03

8-11 Maximum The maximum speed (m/s) Float

12-15 Minimum The minimum speed (m/s) Float

16-17 Counts/rev Encoder counts per revolution UInt16 [1, 65535]

18-21 Revs/meter Motor revolutions/meter Float

22 Parameter 1 Feedback parameter 1 type V or A or X if not present

23 Parameter 2 Feedback parameter 2 type V or Aor X if not present

Response: none

Set Raw Position (0x08)






5-6 Interface Position Closed Loop RotatingMachine Linear Motion ControlInterface

0x03

7 Method Set Value 0x08

8-11 Position The desired ADC Raw Value Unit 32

12 Reserved

Response: Set Position Reply, Over Current Position Reply.


26/43


Page 22

Set Raw Position Reply (0x09)







0x03

7 Method Set Position Reply 0x09

8-11 Raw Position Position Unit32

12 Motor Direction 0 Left /1 Right Unit8

13-16 Current Motor Current Float

Response: none


27/43


Page 23

iGEMS Gamma Radiat io n 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 themethod numbers of the responses to those commands are the same number plus 128.

Get number of events in FIFO (0x04)Byte Name Description Value





5-6 Interface iGEMS Gamma RadiationDetector Interface

0x04

7 Method Get number of events in FIFO 0x04

Response: Return number of events in FIFO

Return number of events in FIFO (0x84)

Byte Name Description Value1 Length (in bytes) The length of the packet 12





0x04

7 Method Return number of events in FIFO 0x84

8,9 # events Number of events Uint16 [0, 2000]

Response: None

Note that only up to 2000 events may be reported even though there are more available the FIFO depthis 5000 events.

Success response (0xFE)

Returned if the last method executed successfully.







0x04

7 Method Return success 0xfe

Response: None
http://www.evproducts.com/http://www.evproducts.com/http://www.evproducts.com/http://www.evproducts.com/


28/43


Page 24

Failure response (0xFF)

Returned if the last method did not execute successfully.







0x04

7 Method Return failure 0xff

Response: None

Clear event FIFO (0x05)

Clear the contents of the FIFO






0x04

7 Method Clear event FIFO 0x05

Response: Success response or failure response.

Get iGEM unit number (0x0B)

Returns the iGEM unit number.







0x04

7 Method Get iGEM unit number 0x0B

Response: ReturniGEM Unit Number

Return iGEM Unit Number (0x8B)







0x04

7 Method Return iGEM unit number 0x8B

8,9 Unit # iGEM Unit number Uint16 [0, 65534]

Response: None


29/43


Page 25

Get detector type (0x0D)

Gets the iGEM detector type.







0x04

7 Method Get iGEM detector type 0x0D

Response: ReturniGEM Detector type

Return iGEM Detector Type (0x8D)







0x04

7 Method Return iGEM Detector Type 0x8D

8 Detector iGEM Detector Type Uint8 [1, 255]

Response: None

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

Get detector bias voltage (0x0F)

Gets the iGEM detector bias voltage.







0x04

7 Method Get detector bias voltage 0x0F

Response: Returndetector bias voltage

Return detector bias voltage (0x8F)







0x04

7 Method Return detector bias voltage 0x8F

8 Detector Detector bias voltage Uint16 [1, 2000]

Response: None


30/43


Page 26

Detector bias voltage from 0 to 2000 is returned.

Set ASIC Gain (0x10)







0x04

7 Method Set ASIC Gain 0x10

8 Gain ASIC Gain Uint8 [0, 1]

Response: Success response or Failure response

Gains are: 018 mV/fC; 136 mV/fC.

Set ASIC Shaping Time (0x11)


1 Length (in bytes) The length of the packet 112 Destination node The responding nodes id [0, 127]




0x04

7 Method Set ASIC Shaping Time 0x11

8 Shaping time ASIC Shaping Time Uint8 [0, 1]


Gains are: 012 s; 12.4 s.

Set High Voltage Level (0x12)

This command sets the output of the HV supply. Usually the value obtained from command 0x0F wouldbe sent. Acceptable values range from 0 to 2047.







0x04

7 Method Set High Voltage Level 0x12

8,9 HV Value Voltage of HV Supply Uint16 [0, 2047]

Response: None


31/43


Page 27

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 tohigh. On power-up the iGEM SM will set this value to 0x0000 (0), FIFO nearly full signal line disabled.







0x04

7 Method Set FIFO Nearly Full Value 0x13

8,9 Value Nearly Full Value Uint16 [0, 5000]


Enable/Disable Event Counter (0x14)

This command is used to enable or disable the event counter. When the event counter is enabled, eachover 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 eventcounter will be disabled.







0x04

7 Method Enable/Disable Event Counter 0x14

8 Setting Enable/Disable Uint8 [0, 1]

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

Read and Reset Event Counter (0x15)

This command is used to read the value of the event counter via the SPI command interface. Once theevent counter value is placed in the SPI transmit buffer, the counter is reset to 0 and over threshold eventcounting will resume.







0x04

7 Method Read and Reset Event Counter 0x15



32/43


Page 28

Return Event Count (0x95)

This response returns the value of the event counter.







0x04

7 Method Return Event Count 0x95

8 Count Event Count Uint16 [0, 65535]


Get N Events (0x40)

This command is used to read the value of N events stored in the FIFO buffer. Each event is an integerless than 4096. N is any number less than 123






0x04

7 Method Get N Events 0x40

8 N Number of events to get Uint8 [1..122]

Response: Return N Events

Return N Events (0xC0)

This response returns the values of the events.


1 Length (in bytes) The length of the packet 10+N*2





0x04

7 Method Return Event Count 0xC0

8,9 Event0 Event 0 Uint16 [0, 4095]

10,11 Event1 Event 1 Uint16 [0, 4095]

.. .. .. Uint16 [0, 4095]

Response: None


33/43


Page 29

Rotat ing Mo tor Pos i t ion Control Interface (0x07)

This interface is for controlling devices that can be set to a range of positions by a rotating motor, therotations of which are counted by an encoder of some sort. A constant of proportionality must existbetween 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 Positionthe encoder counter must be set to zero.The position of the device being controlled is proportional (not necessarily linearly) to the number ofrotations 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 inthe device moving toward its reset position. This implies that the minimum position (as measured byencoder 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 setthrough a specific encoder count that can vary between zero and a maximum value. All devicesimplementing this interface are required to be at the reset position on power-up. If a device is notat the reset position on power-up, it should not be operable until moved to the reset positionunder operator control.

The Set Parameterscommand 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 onlyused at discovery, but could be used at any time to refresh or change those values. The Set Positioncommand tells the device where to move to, and the device responds with the Set Position Replypacketcontaining the value of one or two optional feedback parameters. These feedback parameters can be avoltage (Volts) or a current (Amperes). The Get Position Control Parameter Infopacket asks the deviceto respond with the Return Position Control Parameter Infopacket, containing the encoderproportionality factor (counts per revolution), the maximum encoder count in effect for the device, themaximum speed of the motor, and the definition of the feedback parameter types. The Move to ResetPositioncommand, and a Verify at Reset Position/Reply Verify Resetcommand/response pair areused to determine if the device is at the reset position. The Get Position/Return Positioncommand/response pair are used to get the current position, expressed as an encoder count. Finally, theStopcommand 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 takesome time.






5-6 Interface Position Control 0x07

7 Method Set Position 0x00

8-11 Position The desired encoder count 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 bytesreturned by this reply will depend on whether 0, 1 or 2 feedback parameters have been specified in theReturn Position Control Parameter Info packet.


34/43


Page 30







7 Method Set Position Reply 0x01

8-11 Position Current encoder counts Int32 [0..Maximum]



Float



Float

Response: none

Get Position Control Parameter Info (0x02)







7 Method Get Position Control ParameterInfo

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 encodercounts and motor rotations, the maximum motor speed to use, and which, if any, parameters will bereturned by the Set Position Reply method.






7 Method Return Position Control ParameterInfo

0x03

8-9 Counts/rotation Encoder counts per rotation Uint16

10-13 Maximum The maximum attainable count Int32

14 Speed Maximum motor speed Uint8[1..255]

15 Parameter 1type

Feedback parameter 1 type Character: see below for codes.

16 Parameter 2type

Feedback parameter 2 type 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 sometime for the mechanical device to move to this position. During the time that it takes to move to the reset


35/43


Page 31

position, the device should ignore all commands except the Stop command and the Verify at ResetPosition command.






7 Method Move to Reset Position 0x04

Response: None

Verify at Reset Position (0x05)

This interface is used determine if the device is at the reset position.





4 Subcomponent The interface subcomponent [0, 255]5-6 Interface Position Control 0x07

7 Method Verify at Reset Position 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 resetposition or not at the reset position, or there may have been an error achieving the reset position. Forexample, if there could be a mechanical blockage that keeps the device from achieving the reset positionso that the motor goes into current overload, or there could be a problem with the reset position indicatordevice.






7 Method Verify Reset Reply 0x06

8 Status Reset Position Status Character: Status (see below)

Response: none

Possible status replies are: T - at reset position; F not at reset position; E error when trying toachieve reset position.

Get Position (0x07)Byte Name Description Value






7 Method Get Position 0x07

Response: Return Position


36/43


Page 32

Return Position (0x08)






7 Method Return Position 0x08

8-11 Count The current encoder count Int32 [0..Maximum]

Response: none

Set Parameters (0x09)

This command sets critical parameters: the maximum encoder count allowable for the device, and themaximum speed at which the motor should turn when changing position. The maximum speed is set as asingle 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 SetParameters Response.







7 Method Set Parameters 0x09

8-11 Maximum The maximum encoder count Int32 [0..Maximum]

12 Speed The maximum speed to use Uint8[1..255]

Response: Set Parameters response

Set Parameters Response (0x0a)







7 Method Set Parameters Response 0x0a

Response: none

Stop (0x0b)

This command will stop the motor.







7 Method Stop 0x0b

Response: none


37/43


Page 33

Set Speed Position Control (0x0c)

This command requests the device to move to a specified position with a speed control, expressed as anencoder count. Depending on the difference between the current position and the new one, thismovement could take some time.






7 Method Set Speed Position Control 0x0c

8-11 Position The desired position encodercount

Int32 [0..Maximum]

12-15 Desired Speed Desired speed 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 bytesreturned by this reply will depend on whether 0, 1 or 2 feedback parameters have been specified in theReturn Position Control Parameter Info packet.







7 Method Speed Position Control Reply 0x0d

8-11 Position Current encoder counts Int32 [0..Maximum]

12-15 Current speed Float16-19 Feedbackparameter 1


Float



Float

Response: none

Zero Position (0x0e)






7 Method Set Speed Position Control 0x0e

Response: Zero Position Reply


38/43


Page 34

Zero Position Reply(0x0f)






7 Method Set Speed Position Control 0x0f

Response: None

Au xil iary Con tro l Interfac e (0x08)

This interface is used to control auxiliary components that are included in a device. The interface has twomethods, described below. The Auxiliary Control Setcommand tells the component what it should do,and the device responds with the Auxiliary Control Replypacket containing the value of two optional

feedback parameters.

Arm Raise Control Set (0x00)






5-6 Interface Auxiliary control 0x08

7 Method Arm Raise control set 0x00

8 Control byte 0: No power

1: Power higher2: Power lower3: Get status

UInt8

Response: Arm Raise Control Reply


39/43


Page 35

Arm Raise Control Reply (0x01)





4 Subcomponent The interface subcomponent [0, 255]5-6 Interface Auxiliary control 0x08

7 Method Auxiliary control reply 0x01

8 Control status Raise arm0: No power1: Raising2: Holding raise position3: Lowering4: Holding lower position.5: Calibrating

Uint8

9-12 Position

(degrees)

Arm position Float

Degrees

13-16 Pressure (psi) Touch pressure FloatPsi

131021_inuktunprotocol.pdf

Documents