Basic Reusable Mechanics protocol

Communication

Each message can go in one of two possible directions.
In this document we refer to direction in the terms of who
is sending the message - with two possible sources:

uC - microcontroller (typically Arduino or similar) of the chassis being controlled

SW - controlling software (typically running on a PC)

Message format

Each message is a single line of text, ending with '\n' (0x0A, newline) character.

Allowed are only ASCII printable characters. Actually used are only the characters
explicitly mentioned in any part of this specification.

Each message consists of fields. Each field is delimited by single space ' ' (0x20, space) character.
Fields are numbered from 0 (zero). Numbers in fields are in decimal notation unless specified otherwise.

There are mandatory and optional fields.

Mandatory fields are:

Number

Name

Length

Description

0

MId

2

“Unique” decimal (00-99) identifier, used in replies. Identifier MUST change by 1 every command from SW.
-1 - invalid id received
-2 - special id for alerts

1

Type

1

Specific type or command, must be uppercase letter.

All other fields are optional. They could be mandatory for specific message type (see below).

Messages listing

Type

SW

uC

Short description

C

00 C

00 C M:-99:99 M:0:99 S:0:10

Capabilities

M

00 M #1 #2 [#3 #4 …]

00 M OK

Run motor #1 at speed #2, motor #3 at #4 …

S

00 S #1

00 S #1 #2

Get sensor #1 value, the value is #2

A

—

-2 A #1 [#2 …]

Alert number #1, further fields depend on implementation

E

00 E #1 [0/1]

00 E #1 0/1

Query or enable/disable (1 or 0) some feature

V

00 V #1 [#2]

00 V #1 #2

Get/set configuration variable

W

00 W #1 [#2]

00 W #1 #2

Get/set steering wheel angle - or similar thing

R

—

00 R [#1]

Resend line 00, reason in #1

I

00 I

00 I OK

Reinitialize uC

Possible messages:

Q - query current motor state

T - trigger some action (fire a cannon)

Capabilities

The capabilities message returns a number of fields. Each field has a device type
which should correspond to device command (M for motor, S for sensor…) and allowed
scale, grouped by : character . For binary devices (triggers, lights) it doesn't report scale. Optionally for sensors it may contain “alert” paramteter, which when exceeded emits Alert message. For sensors where high value needs attention (ie. raw IR sensors) use the value as is, for sensors where low walue needs attention (rangefinder) use negative.

Returned fields order does matter. All devices of given type are given a number
according to where they appeared in the capabilities reply. Each device type has
its own numbering starting from 0 (zero).