MarcDuino

Command Reference

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)