Command Reference

MarcDuino Command Reference

Updated on: Dec 8, 2013

Command implementation in v1.6 Pie Panel Control Board (Master MarcDuino)

The MarcDuino Panel Controller master board is used to receive string commands from a serial stream through an  XBee or WiFly radio.

Hardware setup summary

The Master board controls the 10 panel servos, and via RS232 the sound system and the slave HP Controller MarcDuino board.

     - 10 servo outputs for the dome panel doors, headers 1 to 10
     - first software uart (suart) at 9600 bauds connected the slave HP Controller board
     - second software uart (suart2) at 9600 bauds
            connected to the CFIII sound systemwith RS232 level translation
            or connected to the MP3Trigger Rx input
     - main UART at 9600 bauds connected to an XBee or WiFly radio
     - RC input connected to an RC channel from my traditional RC receiver
 

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:  : * @ $ !%

           Pie panel command
      *      HP commands, passed on to the slave MarcDuino board daisy chained to suart1
     @     Display commands, also passed to the MarcDuino board
      $      Sound commands, passed to the CFIII sound controller on suart2 (PC4 on MarcDuino v1, PC1/Sound on MarcDuino v2)
      !       Custom Extension command 1. String following this command is output by Master Board on Suart2
                        - PC4 on MarcDuino v1 (where your sound system should be connected)
                        - PC1/Sound out on MarcDuino v2
                        This allows for custom sound or special systems to be attached to the master at 9600 bauds
      %     Custom Extension command 2. String following this command is output by Slave Board at 9600 bauds. on
                        - Suart2 PC4 on MarcDuino v1
                        - on Suart PC0/Slave out on MarcDuino v2
                        This allows for custom boards such as Arduinos 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 (Both Master and Slave MarcDuino v2, only)

I2C commands are now recognized by the MarcDuino v2 Firmware. If you send a command like:

&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

And of course you can mix everything:
&25,2,xFF,'c,"Hello World

Commands implemented in v1.5 HP Control Board (Slave MarcDuino)


The slave HP MarcDuino board receives the commands forwarded from the master board.
It controls 6 Holoprojector servos, the Magic Panel, and via RS232 the JEDI display system.
(Holoprojector lights are indirectly controlled through the JEDI system)

 MarcDuino connection setup:
     - 6 servo outputs
         Holo 1 V on header 1
         Holo 1 H on header 2
         Holo 2 V on header 3
         Holo 2 H on header 4
         Holo 3 V on header 5
         Holo 3 H on header 6
- servo headers 7 to 9 are not used.
     - one digital output
         Magic Panel on Port B Pin 5
         On header 10.
   
     - software uarts (suart) outputs:
         - suart connected to the JEDI Display light control system at 2400 bauds
         - suart2 initialized at 9600 bauds, for future use (to another daisy chained MarcDuino)
     - one RC input
     - hardware UART input (Rx), connected to the master panel controller suart output at 9600 bauds
    - hardware UART output (Tx) not connected.

 Valid command start characters

*  Holoprojector or Magic Panel command, see below.
@ display command, forwarded to JEDI controller on suart1 after stripping the '@' control character
: panel command, received but ignored.
 $ sound command, received  but ignored.

 

 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)

 JEDI display commands

This command set is not from me, it is defined by the JEDI Display. “@” Commands received by the MarcDuino’s are simply forwarded to the JEDI display. Any command can be sent to the JEDI display via the Master Panel Controller or via the Panel Controller. The command will find its way through the two boards, and be eventually forwarded without change to the attached JEDI system. The special character @ must be added at the beginning of the JEDI command for the MarcDuino boards to recognize it properly and forward it to the JEDI system. The @ character will be stripped before the command is sent to the JEDI display

JEDI Display Command format (also known as "Jawa Light"):

 @xxTyyy\r
(the @ is for the MarcDuino controller to recognize the command as a JEDI command, it then gets stripped before it is sent to JEDI display)
 
 xx= one (or two) digit address, only one in basic system as below:
 0  sends the command to all parts of the display
 1  Top FLD
 2  Bot FLD
 3  RLD
 4  Front PSI
 5  Rear PSI
 6  Front Holo
 7  Rear Holo
 8  Top Holo
 
 T= one letter command, as below:
 T  display mode
 P  parameter
 W  wait
 D  HP off
 M  Set message (for logics)
 
 yyy= parameter value or message string, varies in length and meaning depending on the letter command
 
 "T" commands summary
 T1     default
 T2     flash - permanent on logics/PSI, but HP off after 2s. Follow by a 0W4 to silence after 4 seconds
 T3     alarm - permanent on logics/PSI, but HP off after 2s. Follow by a 0W4 to silence after 4 seconds
 T4     short circuit - lasts for 8 seconds or so
 T5     scream - similar, lasts for a short while
 T6     leia - looong 20 seconds
 T10    Star Wars
 T11    Imperial March - no HPs. Looks more like an "error"
 T92    Spectrum - "Disco" display, works on front logics only
 T100   Display message on logics
 
 "P" commands of interest
 6P91   change HP to digital - will change all HPs
 5P91   change PSI to digital (if Vlechecks connected to rear PSI)
 0P61   characters to Aurabesh
 0P60   characters to Latin (normal)
 
 "Wyy" wait command
 Cancels the previous mode after a yy seconds, doesn't work reliably on all modes.
 For example
 0T2     starts flash mode
 0W4       will stop flash mode after 4 seconds
 
 "M" commands (1=top FLD, 2=bottom FLD, 3=RLD)
 3MHELLO WORLD   \r sets rear logic text to "HELLO WORLD   ", only caps recognized
 
 Example of text handling
 3Mmessage to display in caps\r     presets the text of the logic, but does not display it
 3T100                              switches to message display, of message previously set
 3P61                               changes to Aurabesh
 3P60                               back to Latin
 3T1                                display back to normal random pattern
 
 Example of holo handling (6=front 7=rear 8=top holo)
 6P91   change all HPs to digital
 6T1    turn holo on (this is weird, as 1 should be normal off!)
 6D     turn holo off
 6T4    flickers holo for 4 seconds (using short circuit mode)
 6T6    flockers holo for 11 seconds (using Leia mode)


CuriousMarc's Teeces Command Reference

When running my sketch, the Teeces Lights is able to respond to JawaLite commands, sent via serial at a pokey 2400 bauds to be backwards compatible with the JEDI display. Most JawaLite commands found on the JEDI display are implemented, completed by a few CuriousMarc's Teeces commands that adds even more functionality. A such, when one connects a CuriousMarc's Teeces in place of a JEDI display to the slave HP MarcDuino, all the R2 Touch effects will work correctly.


The JawaLite implementation documentation, available within the sketch, is reprinted below (as of version 1.1):


////////////////////////////////////////////////////////
// Command language reference - JEDI JawaLite emulation
///////////////////////////////////////////////////////

JawaLite command syntax uses plain text format, followed by carriage return. Format is address - command letter - value:
xxYzzz<cr>
where xx= address (one or two chars), Y=command letter, zzz=optional argument, <cr>= carriage return character ('\r'=0x13)

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     - flah, 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 controlled by MarcDuino HP.
0D, 6D, 7D, 8D -> holos off  - not implemented, HP lights controlled by MarcDuino HP.

Command M, set message for the text. 0= all logics, 1=TFLD, 2=BFLD, 3=RLD
0-3Mmessage - where "message" is an 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" 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

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.

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

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 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.

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

For the CF-III sound system, the command is simply forwarded as is to the CFIII sound unit. All sound command decyphering and processing, including random sound generation, is done by the program residing on the CF-III memory card.
For the MP3Trigger system, the MarcDuino interprets 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)