Updated on: May 17, 2018

Command implementation in Firmware v1.6 Master

The MarcDuino Master board is receiving string commands on its serial Rx pin. In the normal configuration this will be connected to an XBee or WiFi radio, but any other source at sending serial information at 9600 bauds, 8 bits, no parity, one stop, will work.

Command Format, Prefix Character

All commands are short ASCII strings.

Each command must start with a prefix character and end with a carriage return (0x13).

The starting prefix character must be one of the following: : * @ $ !%

MarcDuino Command Prefixes are briefly explained below, complete format for each prefix is detailed further down

: Pie panel command

* HP commands

Any * commands received by the Master are passed on to the Slave board

@ Display commands, also passed to the MarcDuino board

Any @ commands received by the Master are passed on to the Slave board

$ Sound commands

! Custom Extension command 1.

! commands received by the Master are passed on to the Sound output (SUART2/PC4 on MarcDuino v1, PC1/Sound on MarcDuino v1.5 and v2), stripped of the ! prefix. This prefix allows for custom sound or special systems to be attached to the Master at 9600 bauds

% Custom Extension command 2.

% commands received by the Master or the Slave are output by Slave Board at 9600 bauds on the Slave Out port (SUART2/PC4 on MarcDuino v1, PC0?/Slave Out on MarcDuino v1.5 and v2) after being stripped of the % prefix. This allows for a third MarcDuino board to be attached to the slave.

& I2C command (MarcDuino v2 firmware only)

Panel commands

They must follow the syntax

:CCxx\r

where CC= two ASCII characters for the command code, xx= two digit decimal number, \r carriage return (0x13)

The following panels commands are recognized:

:SExx

launches sequence xx, see details below

:OPxx

open panel number xx=01-10. If xx=00, opens all panels

OP11= open top panels

OP12= open bottom panels

:CLxx

close panel number xx=01-10, removes from RC if it was, stops servo. If xx=00, all panels, slow close.

:RCxx

places panel xx=01-10 under RC input control. If xx=00, all panels placed on RC.

:STxx

buzz kill/soft hold: removes panel from RC control AND shuts servo off to eliminate buzz.

xx=00 all panels off RC servos off.

:HDxx

RC hold: removes from RC, but does not turn servo off, keeps at last position. xx=00 all panels hold.

Sequences Command details

:SE00 Close all panels (full speed), servo off - use as init only. Use CL00 for all soft close.

:SE01 Scream, with all panels open

:SE02 Wave, one panel at a time

:SE03 Fast (Smirk) back and forth wave

:SE04 Wave 2 (open progressively all panels, then close one by one)

:SE05 Beep Cantina (with marching ants panel action)

:SE06 Faint/Short Circuit

:SE07 Cantina dance (orchestral, rhythmic panel dance)

:SE08 Leia

:SE09 Disco

:SE10 Quite Mode reset (panel close, stop holos, stop sounds)

:SE11 Full Awake Mode reset (panel close, random sound, holo movement, no holo lights)

:SE12 Top Panels to RC

:SE13 Mid Awake Mode reset (panel close, random sound, stop holos)

:SE14 Awake+ Mode reset ((panel close, random sound, holo movement, lights on)

:SE15 Screams no panels

Panel Moves and light display only, no sound

:SE51 Scream, with all panels open

:SE52 Wave, one panel at a time

:SE53 Fast (Smirk) back and forth wave

:SE54 Wave 2 (open progressively all panels, then close one by one)

:SE55 Marching ants

:SE56 Faint/Short Circuit

:SE57 Rhythmic cantina panel dance

I2C Commands (Master and Slave MarcDuino Firmware v1.8 and up only)

I2C capability was added with the MarcDuino boards v1.5, and the MarcDuino boards v2. The corresponding firmware for both boards is rev 1.8. If you send a command following the format:

&I2Caddress, data, data, data...

an I2C write command will be generated on all the I2C ports in the MarcDuino chain (master and all slaves). The write command will be addressed to the device at I2Caddress and will write all the data bytes provided in order.

Data can be decimal numbers, hex bytes, characters or strings, depending on the prefix appended to the data, as follows.

Decimals need no prefix. Valid range is -128 to 255. For example, to send command 2 (decimal) to an I2C device at address 25:

&25,2

To send an hex byte, add x as a prefix. To send the hex byte 0xFF to device 25:

&25,xFF

To send a single character, use the ' prefix

&25,'c

To send a string, use the " prefix. Don't put another " at the end or it will be transmitted as part of the string...

&25,"Hello World (note: there is no second " at the end of the string)

And of course you can mix everything:

&25,2,xFF,'c,"Hello World

Commands implemented in Firmware v1.5 Slave MarcDuino

The slave HP MarcDuino board receives the commands from its Rx pin at 9600 bauds, 8 bits, no parity, one stop. In the normal setup, the Rx pin is connected to the Master board ouptut, and the Slave receives all of its commands as created or forwarded by the Master.

Slave valid command start characters

* Holoprojector or Magic Panel commands. Any * commands received by the Master are simply forwarded to the Slave.

@ display command, forwarded to Teeces controller on suart1 after stripping the '@' control character

: panel command, can be received but will be ignored. Normally processed by the Master and not forwarded.

$ sound command, can be received but will be ignored. Normally processed by the Master and not forwarded.

HP Controller Commands recognized

*RDxx

Random Holo movement (xx=01 to 03). If xx=00 and >3 all random.

*ONxx

Turns Holo Light on (xx=01 to 03). If xx=00 or >3 all lights on

*OFxx

Turns Holo Lights off (xx=01 to 03). If xx=00 turns all lights off

*RCxx

Holo vertical movement under RC control, horizontal centered (xx=01-03).

If xx=00 or >3 all RC

*STxx

reset Holo: stops random movement, servos off, turns lights off, and RC off. 00=all off

*HDxx

hold Holo: stops holo movement and turn servos off, but does not turn light off. 00=all stopped

*MOxx

magic panel on. xx=01 to 98, on from 1 to 98 seconds. 00=off, 99=on permanently

*MFxx

magic panel flicker xx=1 to 99 flicker for 1 to 99 seconds. 00= off.

*H1xx, *H2xx, *H3xx, and *H0xx

Turns on-board HP1, 2, 3, and all holos (H0) for xx seconds

x=99 is permanently on.

x=0 turns holo off.

*F1xx, *F2xx, *F3xx, and *F0xx

Will flicker on-board HP1, 2, 3, and all for xx seconds

x=0 turns holo flicker off.

(x=99 turns holo flicker for 99 seconds, and not permanently)

Dome Lights Command Reference

A MarcDuino dome light command follows the format:

@xxYzzz\r

where xxYzzz is a JawaLite command detailed below.

The JawaLite command set used to control the dome lights was originally defined by Scott Gray for his JEDI system. I later ported JawaLite on my sketch for the Teeces system so it too could be controlled by the MarcDuino system. Both the original JEDI display system and the Teeces system running my sketch will work with the MarcDuino.

Any arbitrary command can be sent to the Teeces via the Master or Slave by simply prefixing the command by the @ character. The command will find its way through the two boards, and will be forwarded to the attached display system with the @ is dropped.

CuriousMarc Teeces JawaLite implementation

When running my sketch, the Teeces Lights respond to JawaLite commands, sent via serial at 2400 bauds (rate chosen for compatibility with the JEDI display). Most JawaLite commands found on the original JEDI display are implemented, completed by a few CuriousMarc's Teeces commands that adds more functionality.

General JawaLite command format: xxYzzz

where xx= address (one or two chars), Y=command letter, zzz=optional argument

xx address field is interpreted as follows:

0 - global address, all displays that support the command are set

1 - TFLD (Top Front Logic Dislay)

2 - BFLD (Bottom Front Logic Display)

3 - RLD (Rear Logic Display)

4 - Front PSI

5 - Rear PSI

6 - Front Holo (not implemented here)

7 - Rear Holo (not implemented here)

8 - Top Holo (not implemented here)

Implemented commands (indicated durations are the sketch defaults, they are adjustable, see below):

Command T

0-5T0 - test (switches all logics to on)

0-5T1 - display to normal random

0T2 - flash, same as alarm

0T3 - alarm for 4 seconds (flashes displays on and off)

0T4 - short circuit (10 seconds sequence)

0T5 - scream, same as alarm

0T6 - leia, 34 seconds (moving horizontal bar)

0T10 - Star Wars. Displays "Star Wars" on RLD, "STARS" on TFLD, "WARS" on BFLD

0T11 - March (alternating halfs of logics, 47 seconds)

0-3T92 - spectrum, bargraph displays. Runs forever, reset by calling to 0T1

0-3T100 - Text displays. Displays text set by the M command below

6T1, 7T1, 8T1 - holos on: not implemented, HP lights directly controlled by MarcDuino Slave.

0D, 6D, 7D, 8D - holos off: not implemented, HP lights directly controlled by MarcDuino Slave.

Command xMmessage, set message for the text.

x=0: all logics, 1: TFLD, 2: BFLD, 3: RLD

message: ASCII string to be displayed. Only uppercase implemented.

Command P, character set

0-3P61 - swtich display to aurabesh characters

0-3P60 - switch display to latin (e.g.english) characters

Extended "CuriousMarc Teeces" only commands:

Extra command T to turn displays off

0-5T20

Command R, adjusts random style:

0-3Rx where x=0 to 6.

Command S, PSI state

0,4-5S0 - PSI all on (same as 4-5T0)

0,4-5S1 - PSI normal mode (same as 4-5T1)

0,4-5S2 - PSI first color

0,4-5S3 - PSI second color

0,4-5S4 - PSI off

Scott Gray's JawaLite implementation

For reference only, the original JawaLite as implemented in the JEDI system can be found here.

Sound commands (CF-III or MP3Trigger sound systems)

Sound files organization

The sounds are organized in banks of similar sounds. A sound is accessed programmatically by its bank number and its number within the bank, not by its file name on the memory card. The actual file name of the sound depends on the particular implementation of the sound subsystem. At present, the R2 Touch/MarcDuino supports two sound systems, the CF-III sound system and the MP3Trigger board.

My original CFIII sound implementation uses the following naming convention for the sound files on the memory card:

CF-III sound file naming convention:

Bank 1, generic sounds, files named: gen-x.wav, where x is the number of the sound (1 to 99)

Bank 2, chatty sounds: chat-x.wav

Bank 3, happy sounds: happy-x.wav

Bank 4, sad sounds: sad-x.wav

Bank 5, whistle sounds: whis-x.wav

Bank 6, scream sounds: screa-x.wav

Bank 7, Leia sounds: leia-x.wav

Bank 8, musical sounds: mus-x.wav

Bank 9, user sounds: user-x.wav (not used by R2 Touch, but accessible grammatically or through the CF-III contacts)

The later MP3Trigger sound implementation uses a numbering convention for sound files, and is limited to 25 sounds per bank. The suffix of the file (-xxx) can be anything. There is no bank 9.

MP3 Trigger sound file naming convention:

Bank 1, generic sounds, files named 001-xxx.mp3 to 025-xxx.mp3

Bank 2, chatty sounds: 026-xxx.mp3 to 050-xxx.mp3

Bank 3, happy sounds: 051-xxx.mp3 to 075-xxx.mp3

Bank 4, sad sounds: 076-xxx.mp3 to 100-xxx.mp3

Bank 5, whistle sounds: 101-xxx.mp3 to 125-xxx.mp3

Bank 6, scream sounds:126-xxx.mp3 to 150-xxx.mp3

Bank 7, Leia sounds:151-xxx.mp3 to 175-xxx.mp3

Bank 8, musical sounds:176-xxx.mp3 to 200-xxx.mp3

Startup Sound: 255-xxx.mp3

Sound Command format

Sound commands sent to the MarcDuino must follow the format:

$soundcommand\r

In the Master firmware targeting the CF-III sound system, the string command is simply forwarded as is to the CF-III sound unit after stripping the beginning $. Sound command processing, including random sound generation, is done by the procesor in the CF-III unit itself, which executes a program residing on its memory card.

In the Master firmware targeting MP3Trigger system, the MarcDuino processes the command, and sends play commands to the MP3Trigger. All sound command deciphering and processing, including random sound generation, is handled by the MarcDuino firmware.

Sound Commands Reference

$x

If x is between 1 and 4:

Play next sound from bank x

If x is between 5 and 9:

Play first sound from bank x. Bank 9 not implemented on MP3Trigger platforms.

$xy or $xyy

Play sound y or yy from bank x (x from 1 to 9, y from 1 to 9, yy from 10 to 99). MP3Trigger platform implements sounds only up to yy=25.

$R

Start playing sounds randomly chosen from banks 1 to 5, at random intervals

(no sounds from banks 6-9 will be played in random mode)

$O

(capital letter O) Random Off

$s

Stop any current playing sound, and cancel random mode.

$-

Volume down

$+

Volume up

$m

Volume mid

$f

Volume max

Some particular sounds have been given their own command for convenience. They point to specific files numbers, and you can only change their assignment by editing the code:

$S

Scream (bank 6 sound 1)

$F

Faint/short circuit (bank 6 sound 3)

$L

Leia message (bank 7 sound 1)

$c

Short Cantina music (bank 8 sound 1)

$W

Star Wars (bank 8 sound 2)

$M

Imperial March (bank 8 sound 3)

$C

Long Cantina music (bank 8 sound 5)

$D

Disco Star Wars music (bank 8 sound 6)

@xxYzzz\r

Chaining Commands

This topic is actually related to the R2 Touch app customization more than the MarcDuino proper. A frequently asked question is how to combine two actions on one command in R2 Touch. You need no separators besides the carriage return (\r in the app) that normally terminates each commands. So to play a sound from bank 1 using the $1 command and open all dome panels using the :OP00 command you'd send them straight back to back:

$1\r:OP00\r

Sometimes it takes some time to process a command and you need to insert a short pause between commands using the \p character to allow for the previous command to be executed properly. This happens when chaining commands that go to the Teeces for example, as the link between the MarcDuino and the Teeces is very slow at 2400 bauds, and sending a text string to be displayed might take a while to be completed. You can even put several \p to extend the delay. Each \p is 100 ms. So for example, combining setting the text to the Rear Logic Display (3) to HELLO using the @3M command,, displaying it using the @3T command, and playing a sound using the $1 command:

@3MHELLO\r\p\p\p@3T\r\p$1\r

Note that the \p delay is actually detected and executed on the app side, removed from the stream, and not transmitted to the MarcDuino. If you are commanding the MarcDuino from your own controller, like in the SHADOW system for example, you'll have to implement the delays between commands yourself and cannot use the \p shorthand.