Commit 85d4d2ed authored by Daniel Gröber's avatar Daniel Gröber
Browse files

docs

parent 42ecc53f
Robo command reference
======================
Communication with the robot is done using a 3V3 or 5V serial (UART) connection
at 115200 baud with no parity and one stop bit (default settings for most serial
terminal programs)
On a GNU/Linux system you can connect to the serial console using a terminal
program like minicom but I find these quite cumbersome and recommend 'picocom'
or 'screen' instead. Examples `picocom -b115200 /dev/ttyUSBx`,
`screen /dev/ttyUSBx`.
Since these programs send all typed keystrokes to the serial device they can be
tricky to get out of, for 'picocom' the magic key sequence is `C-a C-x`. That's
holding the Ctrl key while pressing and releasing the "A" key followed by the
"X" key, Ctrl can be let go of in between, doesn't matter. For screen it is
`C-a C-d`
On power-on the robot will send some debug info most of which should be ignored:
hello world
rcc
adc calibrate
adc setup
adc chans: xxxx
gpio setup
adc enable
robo v5
The only interesting bit is "robo v5", this is the combined software and
hardware version of the robot. After this line is sent the robot will wait for
commands. The current hardware revision is v5 and the current software version
is omitted in the first release. Future software releases on v5 hardware will be
numbered v5.1, v5.2 and so on.
The command format is stack based, the robot expects zero or more arguments to
be pushed onto the stack followed by a command code. The command's arguments
will be absent from the stack after it's execution. If insufficient commands are
on the stack an error is returned.
The command interface of the robot is designed to be human operable for easy
exploration. This means the robot will immediately echo any character sent (so a
serial terminal program can be used without additional setup) and commands sent
to the robot are terminated by an (optional) CR (ASCII 0x0d) followed by LF
(ASCII 0x0a) we call this the EOL (end of line) sequence. When responding to
commands (other than the inherent echo) CR followed by LF is always used to
denote the EOL.
Arguments are formatted as signed hexadecimal numbers without a "0x" prefix,
i.e. /-?[0-9]{1,4}/. Examples: the hex numbers (0, 1234, bfff, -cafe, -80)
represent decimal numbers (0, 4660, 49151, -51966, -128) respectively. Commands
are simply single letter characters.
To push an argument onto the stack we send the characters representing it's
value at the beginning of a line followed by the EOL sequence.
To empty the stack we send the EOL sequence at the beginning of a line.
Unknown commands, errors and invalid arguments do not alter the stack's state
and are indicated by the robot sending the character "N" followed by the EOL
sequence.
Thus if the robot is in an unknown state sending the EOL sequence twice will
always result in the robot being at the beginning of a line with an empty stack.
In the following examples ">" denotes host to robot comms (request) and "<"
denotes robot to host comms (response).
Command code reference
---
- "i" -- Set motor target velocity
Request format:
[left_motor (-0x8000..0x7fff)]
[right motor(-0x8000..0x7fff)]
i
Response format:
I
(Just the letter capital "I" on a line of it's own)
Example:
Set left motor velocity to -0x4000/0x8000 = -0.5 i.e. half of
maximum velocity in reverse direction and right motor velocity to 0.5
in the forward direction.
>-4000
<-4000
>4000
<4000
>i
<i
<I
- "s" -- Stop (set left and right motor target velocity to 0)
Request format:
s
Response format
S
- "o" -- Set servo level
Request format:
[servo_level (0..ffff)]
o
Response format:
O
- "q" -- Query distance sensors
Request format:
q
Response format
Q [S1] [S2] [S3] [S4]
Example:
>q
<q
<Q fff 468 1285 164
The returned numbers are 12 bit values representing the voltage returned by
the optical distance sensors, call these numbers S1..S4. To calculate the
voltage each of these values represents: For x = {1,2,3,4}.
Vx = ( 3.3 / (2^12 - 1) ) * Sx
- "d" -- Query motor encoder deltas
Request format:
d
Response format:
D [d_systicks] [delta_left] [delta_right]
Example:
>d
<d
<D 16 -123 654
This means the last "d" query occurred 16 systicks ago. Since then the left
motor moved by -0x123 ticks (i.e. in the reverse direction) and the right
motor moved 0x654 ticks in the forward direction.
- "v" -- Query velocity
Request format:
v
Response format:
V [velo_left] [velo_right]
BUG BUG BUG (robo v5): The numbers returned here are in signed decimal
notation instead of hex.
Example:
>v
<v
<V 75 -73
This means the left motor is moving at a rate of 75 encoder ticks per systick
in the forward direction and the right motor is moving at 73 ticks in the
reverse direction.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment