-
Notifications
You must be signed in to change notification settings - Fork 7
/
Copy pathprotocol.txt
551 lines (391 loc) · 21.4 KB
/
protocol.txt
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
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
TOAD4 communication protocol for firmware version 1.5.x
Author: Kustaa Nyholm
Date: 13.6.2014
License: Creative Commons Share Alike
Introduction
This document describes the communication protocol for TOAD4 firmware.
TOAD4 is a 4-axis motor controller with USB interface based on PIC18F4550 and
it is aimed for CNC applications. It supports commands queues for un-interrupted
movements and position capture to implement probing. It also supports digital I/O
and analog (PWM) output.
TOAD4 is intended to be used with EazyCNC software in which case the information
in this document is not needed, this document is intended for the developers
wishing to use the TOAD4 for something else or needing to understand the
communication protocol in detail.
Chapter 1 - Virtual Serial Port
To the operating system TOAD4 appears as a USB CDC ACM device i.e. virtual serial port.
In Windows it looks like a COM port, Mac OS X it appears as a '/dev/tty.usbmodem*' and
in Linux look for '/dev/tty.ACM*'. (Actually it maybe better to open the device using
the name 'cu.*' instead of 'tty.*').
As this is a virtual serial device the baud rate etc is immaterial and no attempt should
be made to set it.
Chapter 2 - Protocol Overview
The protocol is binary (as opposed to text) for efficiency and space considerations and
thus it is futile to try to communicate with TOAD4 using a terminal, besides timing
is not suitable for keyboard entry.
The protocol is based on messages that contain one or more commands.
The communication is a simple master/slave protocol where master (PC) sends
a message and the slave (TOAD4) responds. TOOD4 will never send anything unless
asked for.
TOAD4 will always wait for a complete message before attempting to interpret it.
If a complete message is not received within 21.7 msec TOAD4 will disregard all
bytes received so far and will start to look for a byte with the MSB set.
If TOOAD4 does not respond or responds badly the master needs to
keep a pause longer than 30 msec and then start with a new complete message.
This is important to synchronize both ends of the communication, both initially
or in case of an error (note that since this is a virtual serial port on top
of USB protocol communication errors are very, very rare).
Chapter 3 - Message Format
A message is a series of bytes that is preceded with a byte that has the MSB bit set
and lower seven LSB bits contain the line length and followed by a check sum. The
maximum length of a message all bytes included is 32 bytes.
The length does not include the length byte itself i.e. it is the number of bytes
TOAD4 will read after seeing the first byte of the message before attempting to
interpret the message.
The check sum is a simple 8 bit unsigned sum of the pay load of the message i.e. the
sum of all bytes excluding the first (the length) and last (the checksum) bytes with
a seed value of hex 0x55 for the sum.
Each command start with a byte that identifies the command and motor it refers to,
followed by zero or more parameters related to the particular command. The three
LSB bits of the byte define the motor and the seven MSB bits define the command.
For each message TOAD4 responds with a corresponding return message that
has the same overall format i.e. it starts with the 0x80 + length byte,
followed by the payload and ends with a checksum.
The return message payload contains a response for each command that was
sent to the TOAD4 in the same order as the commands were sent. The response
is a byte error code followed by zero or more return values depending on
the command.
Chapter 4 - Motion control
4.1 - Position Counter
TOAD4 maintains a position counter for each motor which is simply
a signed 32 bit counter that is incremented or decremented every time the
firmware generates a step pulse for a motor.
In 'forward' direction the position counter is incremented for each
step performed and the direction control output is in forward state.
In 'reverse' direction the counter is decremented and the direction output is
in reverse state.
The hardware state (ON/OFF, 1/0) for forward and reverse states of the
direction output are configurable, see CMD_SET_MODE.
4.2 - Step rate
For commands that specify the step rate i.e. velocity of a stepper it is
specified with a 16 bit unsigned integer value in the range 0..65535.
To convert this value to steps / second use:
steps_per_second = (velocity_value / 65536) * 11718.75
The stepping signal is generated by continuously adding (in a 11718.75
kHz timer interrupt routine) the 16 bit unsigned speed value to
a 16 bit unsigned counter and when ever this counter overflows a step
is generated.
This gives the slowest possible step rate of about one step every 5th
second and highest step rate of little over 11 kHz.
Note that there is jitter in the generated step signal which is
proportional to the step rate. For a speed value of S the jitter
max is in the ball park of S/65536 * 100% percentage. Depending on
the stepper motor and mechanics jitter is the limiting factor
for highspeed operation.
4.4 Command execution and queuing
Most commands are executed as soon as they are interpreted but movement commands
are queued and synchronized. This means that up to 16 movement commands can be
sent to the TOAD4 and it will execute those commands one after the other as
the movements are completed. Synchronizing ensures that movement commands are
executed before previous move commands for all motors have completed.
4.5 - Movement/queue synchronization
When a motor is configured (with CMD_SET_MODE command) a bit mask is given
that specifies which queues/motors this motor should be synchronized with.
Specify a 1 in the mask for each motor you need to synchronize the motor
with, bit 0 (LSB) corresponds to motor 0, bit 1 to motor 2 and so on.
Chapter 5 - Commands
5.1 - Command id byte
As mentioned above each command starts with a byte that identifies the
command and the motor it refers to.
The least significant 3 bits specify the motor so up to 8 motors
can be controlled (but TOAD4 only supports 4) and the 5 most
significant bits identify the command so there can be a maximum of
32 commands, of which 18 are currently implemented and are described here.
5.1 - Return values
All commands return a one byte error code which is one of the following:
ARG_OK 0
ARG_MISSING 1
ARG_QUEUE_FULL 2
ARG_RESP_TOO_LONG 3
ARG_BAD_COMMAND 11
ARG_LINE_TOO_LONG 12
The normal return code ARG_OK (0) indicates that the command execution
was successful.
ARG_MISSING indicates that the message TOAD4 received was too short and
did not contain enough data/parameters for the commands it contains.
ARG_QUEUE_FULL indicates that a move command (CMD_MOVE_DISTANCE) was
attempted but the queue for that motor was full.
ARG_RESP_TOO_LONG indicates that the response requested/required by the
commands exceeded 48 bytes, ie too many commands were sent to TOAD4
in a single message.
ARG_BAD_COMMAND indicates that the command identified by the first
byte of a command was not one of those supported by TOAD4 and specified
here.
ARG_LINE_TOO_LONG indicates that the message was longer than 32 bytes
so the message is disregarded.
Chapter 6 - Command details
The following description of the commands are formatted like this:
Command: Command name
Id: The command number (shift left three times and stick to the first byte with
relevant motor number in the three least significant bits.
Parameters: Short description of the parameters the command takes and their types:
Returns: Short description of the return values and their types
Paramter type coding:
(B) Byte (Unsigne 8 bits)
(DB) Double Byte (16 bits, MSB first)
(QB) Quad byte (32 bits, MSB first)
(S) Signed
(U) Unsigned
-------------------------------------------------------------------------------
Command: CMD_MOVE_DISTANCE
ID: 1
Parameters: Distance (DB,S)
Speed (DB,U)
Returns: Error code (B,U)
Description: This command queues one move command into the specified motors
command queue. The movement will be executed once all the
commands put into the queue prior to this have been completed
in all the synchronized queues.
If queue processing has not been enabled with CMD_ENABLE_QUEUE
then the commands are queued but not executed until the queue
is enabled, this allows 'pre-loading' of the queue without
actually causing any moves.
The Distance parameter gives the signed distance to move in steps.
Negative values indicate 'reverse' and positive 'forward' direction.
The Speed parameter gives the unsigned step rate in units of
11718.75 / 65536 steps/second.
-------------------------------------------------------------------------------
Command: CMD_JOG_REVERSE
ID: 2
Parameters: See CMD_JOG_FORWARD
Returns: Error code (B,U)
Description: Same as CMD_JOG_FORWARD but the direction is towards negative
axis
-------------------------------------------------------------------------------
Command: CMD_JOG_FORWARD
ID: 3
Parameters: Lo-velocity (DB,U)
Hi-velocity (DB,U)
Acceleartiion (DB,U)
Min crawl distance (DB,U)
Crawl (DB,U)
Timeout (QB,U)
Returns: Error code (B,U)
Description: This command sets up and starts jogging. During joggin the motor
runs as long as CMD_CTRL_JOG commands are sent to the TOAD4.
The Lo-velocity parameter specifies the starting and lowest velocity
used during jogging.
The Hi-velocity parameter specifies the top velocity used during
jogging.
The acceleration parameter specifies the acceleration used to
ramp from Lo velocity to Hi velocity, in units of 11718.75 / 65536
steps/second squared
The Min crawl distance specifies the minimum number of steps the
motor will jog regardless how soon it is stopped.
The crawl parameter specifies how long a distance the motor
will run at the Lo velocity before it will accelerate to the
Hi velocity.
The timeout specifies the number of steps the motor will take
before it stops if it does not receive a new CMD_CTRL_JOG command.
If no new CMD_CTRL_JOG command is received the motor will start
to decelerate to the Lo-speed and once it reaches that it will stop.
-------------------------------------------------------------------------------
Command: CMD_RESET_QUEUE
ID: 8
Parameters: -
Returns: Error code (B,U)
Description: This command empties the command queue and places it the disabled
in which commands can be received and queued but are not executed.
-------------------------------------------------------------------------------
Command: CMD_ENABLE_QUEUE
ID: 9
Parameters: -
Returns: Error code (B,U)
Description: This command enables queued command execution. In this state
commands from the queue are executed as long and as soon as
there are commands in the queue.
-------------------------------------------------------------------------------
Command: CMD_QUEUE_STATE
ID: 10
Parameters: -
Returns: Error code (B,U)
State (B,U)
Size (B,U)
Capacitu (B,U)
Description: This command returns the queue state for the given motor.
The State returned gives the internal state machine state
for the given motor, used for debugging.
The Size returned is the number of commands currently in the queue.
The Capacity returned is the maximum number of commands the queue
can hold, so the number of free places in the queue is
Capacity - Size
-------------------------------------------------------------------------------
Command: CMD_MOTOR_STATE
ID: 11
Parameters: -
Returns: Error code (B,U)
State (B,U)
Description: This command the internal state machine state for the given motor,
used for debugging.
-------------------------------------------------------------------------------
Command: CMD_SET_MODE
ID: 12
Parameters: Sync flags (B,U)
Enable (B,U)
Full torque (B,U)
Home polartiy (B,U)
Direction polarity (B,U)
Returns: Error code (B,U)
Description: This command sets the motor drive current and configures the polarity
of the Home and Direction signals. It also specifies which motors
this motor is synchronized with.
The Sync flags parameter is a bit mask with a bit set to one for
each motor that is synchronized together. LSB (bit 0) represents
motor 0 and so forth.
The Enable parameter controls weather the Enable signal is turned
on or not and thus weather the motor driver circuitry for the motor is
is on or not. If not enabled the will not run and the driver is
in high impedance state letting the motor move freely with external
forces.
The Full torque parameter controls weather the Torque signal for the
given motor is turned on or not. If the signal is turned on then the
driver circuitry will supply high current to the motor, otherwise
it will supply low current. Actual current values depend on the
the jumpers settings and current measurement resistor values on the
TOAD4 board.
The Home polarity parameter specifies weather the Home/Ref signal is
1 or 0 when the motor/axis is at low end of the axis travel, low meaning
that coordinates at the end of the travel are smaller that at
the high end.
The Direction polarity parameter specifies weather the direction
signal is 1 or 0 when the motor is driven/stepped to the forward
direction.
-------------------------------------------------------------------------------
Command: CMD_SEEK_HOME
ID: 13
Parameters: Lo-velocity (DB,U)
Hi-velocity (DB,U)
Acceleration (DB,U)
Timeout (QB,U)
Returns: Error code (B,U)
Description: This command causes the motor seek the Home/Ref switch.
If the motor is not 'at home' when this command is given
the motor will run in reverse direction at the speed given
by the Hi-velocity parameter.
Once the Home/Ref signal becomes active the motor will back out
from that position running the motor forward at the speed given
by the Lo-velocity parameter.
If above process cannot be completed within the number of
steps given by the Timout parameter the process is aborted.
-------------------------------------------------------------------------------
Command: CMD_CTRL_JOG
ID: 14
Parameters: Jog flag (DB,U)
Returns: Error code (B,U)
Description: This parameter re-sets the CMD_JOG_FORWARD/Timeout parameter. By
sending this command repeatedly with a small Jog flag value the
jogging is kept running as long as the commands are sent. This
implements a sort of dead man switch i.e. the motor will stop
if the communication from the host stops.
-------------------------------------------------------------------------------
Command: CMD_SET_POS
ID: 15
Parameters: Position (QB,U)
Returns: Error code (B,U)
Description: This command re-sets the 32 bit signed position counter for the
given motor to the value given by the Position parameter and
all further stepping will then increment or decrement from that
value and be reported by the CMD_GET_POS command.
-------------------------------------------------------------------------------
Command: CMD_GET_POS
ID: 16
Parameters: -
Returns: Error code (B,U)
Position (QB,U)
Description: This command returns the 32 bit signed position counter.
-------------------------------------------------------------------------------
Command: CMD_GET_VERSION
ID: 17
Parameters: -
Returns: Error code (B,U)
Version string 16 x (UB) (terminated string)
Description: This commands returns the firmware version and hardware build in the
form of a null terminated C-style string. Regardless of the length
of the string 16 bytes are always returned. The version number has
the following format.
major.minor.fix-build
Major value gets incremented when new features are added or removed from
the firmware which make it incompatible with previous versions.
Minor value gets incremented when new features are added, in general the
firmware remains compatible with the older versions.
Fix gets incremented if a bug is fixed and the firmware remains fully
compatible with the previous versions
Build indicates which version of hardware the firmware has been built for.
Value of 4 indicates the current (as of this writing) TOAD4 hardware.
-------------------------------------------------------------------------------
Command: CMD_ARM_PROBE
ID: 18
Parameters: Stop speed (DB,U)
Deceleration (DB,U)
Returns: Error code (B,U)
Description: This commands arms the position capture or probe feature. When armed
the values of all stepper motor position counters are copied to
a capture memory when the probe signal activates and the motors
are brought to stand still.
The Deceleration parameters specifies the deceleration used to
bring the motors to a stop.
The Stop speed parameter specifies the low speed at which or
below the motor is completely stopped when it is being decelerated.
-------------------------------------------------------------------------------
Command: CMD_GET_PROBE_POS
ID: 19
Parameters: -
Returns: Error code (B,U)
Position (QB,U)
Description: This command returns the 32 bit signed captured 'probe' position
for the given axis. If the probe is still armed i.e. it has not
triggered yet and thus no probing has taken place this command
return the value of 0x80000000 or -2147483648.
-------------------------------------------------------------------------------
Command: CMD_CONFIG_PROBE
ID: 20
Parameters: Input (B,U)
Value (B,U)
Returns: Error code (B,U)
Description: This command configures which input and which state of that input
is used to trigger the probe function.
The input parameter specifies the input to be used, current firmware
ignores this parameter and always uses the PROBE signal.
The value parameter specifies the value (1 or 0) that will trigger
the probe position capture.
-------------------------------------------------------------------------------
Command: CMD_SET_OUTPUT
ID: 21
Parameters: Output (B,U)
Value (B,U)
Returns: Error code (B,U)
Description: This command is used to set a given output to a given value.
The output parameter specifies the output affected.
Valid outputs and values and the corresponding hardware signal are:
Output 0, Values 0/1, SPINDLE_FWD
Output 1, Values 0/1, SPINDLE_REV
Output 2, Values 0..255, SPINDLE_SPEED (analog/pwm signal)
Output 3, Values 0/1, COOLANT
-------------------------------------------------------------------------------
Command: CMD_GET_INPUT
ID: 21
Parameters: Input (B,U)
Returns: Error code (B,U)
Value (B,U)
Description: This command returns the state (0/1) of the given input
on the TOAD4 board.
The inputs are numbered thus:
0 HOME_X
1 HOME_Y
2 HOME_Z
3 HOME_4
4 PROBE
-------------------------------------------------------------------------------
Rather than trying to verbally describe this further I think it is best to refer
to the Java code for the nitty-gritty details of communicating with TOAD4,
See the classes in package 'eazycnc.toad4'.