-
Notifications
You must be signed in to change notification settings - Fork 0
/
hyperbola_core
193 lines (155 loc) · 7.41 KB
/
hyperbola_core
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
The Hyperbola Protocol is a simple addressed TLV stream,
modeled loosely on MIDI and the OpenAMD protocol set.
The packet framing is composed of the following one-byte fields,
which prefix data.
The constant byte 0x55
A destination identifier/broadcast (sim. MIDI channel)
A source identifier
A flag & packet length (of the data inside the frame) byte
A command byte
On byte-wise transports, we suggest imposing a timeout rule of the form "if
the line idles for more than N byte times while framing, reset the state
machine." On packetizing unreliable transports, we suggest not having
Hyperbola packets straddle link-layer packets.
Transports with their own framing may opt to elide or translate header
fields, so long as the mapping is bijective and reversed.
Transports MUST be able to handle packets as large as 31 bytes of payload.
The most significant three bits of the lengh byte are flags in the Hyperbola
protocol, leaving 5 bits (0-31) for the payload length.
0x80 -- RESPONSE, meaning that this is not a command.
0x40 -- RESERVED MAINTAIN ZERO
0x20 -- RESERVED MAINTAIN ZERO
There is a region of common commands understood by all Hyperbola
devices (values 0x00 to 0x0F) and a region which is target device
specific.
The destination identifier 0xFF is reserved for broadcast and should only be
used to carry payloads with common commands. Hyberbola devices have a 4
byte device type ID and a 4 byte serial number (unique only within device
types). Device ID 0 is reserved for "all devices"; serial number 0 is
reserved to indicate "all units" of a given device type. Broadcast packets
may not contain device-specific command bytes, so the range 0x10 to 0xFF
is again defined by this document.
As Hyperbola transits networks with various reliability guarantees, it is
recomended that commands attempt to be as idempotent as possible. That
said, it is in general impossible to derive a shared consensus of reality
over an unreliable link, so some slack is permitted.
Common commands:
0x00 IDENTIFY THYSELF
The payload begins with a four-byte opaque value, which is
echoed in responses.
The payload continues with a mode-dependent header:
Broadcast carrier, specific device:
device type ID, serial number
Broadcast carrier, all devices of a given type:
device type ID, 0x00000000
Broadcast carrier, all devices of all types:
0x00000000, 0x00000000
(or ommitted in query)
Unicast carrier:
may be omitted (ignored if present)
Sends a (unicast) response to the source containing:
the opaque value,
this node's device type
serial number
additional device-type specific data
The "source indicator" for this response shall be the broadcast
address if the device does not have an address configured.
0x01 SET ADDRESS
As a broadcast payload, expects a payload containing:
The device type ID
The device serial number
The new device address
In unicast payload, expects only the new device address.
Responds from the new device address with an identical payload.
0x02 SET UNDERLYING COMMUNICATIONS PARAMETERS
Establishes parameters for the underlying communication (e.g. radio
parameters as appropriate). Commands begin with a single byte
payload:
0x00 CANCEL
0x01 ENQUEUE
0xFF APPLY
Note that the contents of this payload after the initial header are
device specific.
This command is only accepted as a unicast payload.
As it may take many commands to set all the parameters of a device,
changes should be buffered until a finalize subcommand is sent. All
responses, including to the command which applies the changes, are
sent using the old parameters.
Responses contain a single byte, paralleling the header, with 0x00
being interpreted as "unable to comply", 0x01 indicating a
successful parse, and 0xFF indicating that changes have been
applied.
It is RECOMMENDED that Hyperbola devices have a fixed-function
format fallback mechanism for configuration in addition to their
primary interface. It is highly suggested that this be 3-wire
TTL UART at 9600 8n1, speaking Hyperbola.
0x08 REALLY TRIVIAL FILE TRANSPORT PROTOCOL : READ
0x09 REALLY TRIVIAL FILE TRANSPORT PROTOCOL : WRITE
rTFTP is even simpler than TFTP. Not all device types support
rTFTP. Those that do must indicate various bounds in their
IDENTIFY THYSELF responses.
These commands are brought out to the core merely to reduce
duplication in the per-device specifications.
rTFTP understands up to 256 "files" of 4096 bytes each, but again,
devices may not have that many "files", may view "files" as a larger
offset into a singular dataset, or may have many shorter files. It
is device-specific as to how to safely enter and exit rTFTP mode.
Read requests are two bytes: file and 16-byte boundary index.
Read responses echo the header then have an error code
followed by a code-dependent payload:
0x00 : success -- followed the 16 bytes in question.
0xFF : no such file
0xFE : request out of bounds
0xF1 : Sender has fallen behind receiver (message duplicates
an already acknowledged message)
0xF0 : protocol violation, some number of writes may have
been lost. Restart the file transfer.
Write requests have the same header and then the 16 bytes of data.
Write responses look like read responses.
Broadcast-only notices
Unlike commands, these packets do not elicit responses to the
originating node.
0x10 BEACON
Devices may optionally signal, via BEACONs, that they are on.
This may also be useful as a primitive form of BOOTP for address
assignment.
The payload here is an IDENTIFY THYSELF response with a monotonic
increasing (with wraparound) opaque value.
0x20 SINGLE EVENT REPORT
While Hyperbola devices may have pub/sub style handling of events,
occasionally it is useful to have event notices hit the entire
network. This is intended for rare event notification from devices
on the network, and may be used even by devices that do not have
addresses.
The payload here is 13 bytes:
device type ID
device serial number
event value (4 bytes)
device-specific event ID (1 byte)
0x21 BROADCAST ALERTS
This event is intended as a mechanism for wide-scale information.
The payload here mimics SINGLE EVENT REPORTS but the sub-command
byte vocabulary is common:
device type ID
device serial number
sub command (1 byte)
optional suffix, up to 8 bytes.
Currently, the only sub-commands defined are a color code sequence,
used to provide a rapid, network-wide means of shutting down or
clamping actuators on the network. These commands do not have
optional suffixes, and any suffix must be IGNORED.
0xFF RED All actuators are to return to default state
immediately; controllers should enter their
reset configurations.
0xFC YELLOW Any "increasing" actuator slews are frozen
in time, if possible. If this is not possible,
this message SHALL be treated as RED.
0xF8 GREEN Signals clearance to lift temporary restrictions
imposed by YELLOW messages, if possible.
Some actuators may consider themselves unsafe at any speed
without a continuous stream of GREEN messages; this knowledge is
conveyed by the device's type identifier or device-type-specific
data. Additionally, since broadcast messages may be lost in an
unreliable shared channel (e.g. radios) we suggest that color
status, if employed, be repeatedly sent at a relatively high
rate.