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
Any * commands received by the Master are passed on to the Slave board
Any @ commands received by the Master are passed on to the Slave board
! 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
% 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.
They must follow the syntax
where CC= two ASCII characters for the command code, xx= two digit decimal number, \r carriage return (0x13)
The following panels commands are recognized:
launches sequence xx, see details below
open panel number xx=01-10. If xx=00, opens all panels
OP11= open top panels
OP12= open bottom panels
close panel number xx=01-10, removes from RC if it was, stops servo. If xx=00, all panels, slow close.
places panel xx=01-10 under RC input control. If xx=00, all panels placed on RC.
buzz kill/soft hold: removes panel from RC control AND shuts servo off to eliminate buzz.
xx=00 all panels off RC servos off.
RC hold: removes from RC, but does not turn servo off, keeps at last position. xx=00 all panels hold.
Sequences Command details
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:
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:
To send an hex byte, add x as a prefix. To send the hex byte 0xFF to device 25:
To send a single character, use the ' prefix
To send a string, use the " prefix. Don't put another " at the end or it will be transmitted as part of the string...
And of course you can mix everything:
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
HP Controller Commands recognized
Random Holo movement (xx=01 to 03). If xx=00 and >3 all random.
Turns Holo Light on (xx=01 to 03). If xx=00 or >3 all lights on
Turns Holo Lights off (xx=01 to 03). If xx=00 turns all lights off
Holo vertical movement under RC control, horizontal centered (xx=01-03).
If xx=00 or >3 all RC
reset Holo: stops random movement, servos off, turns lights off, and RC off. 00=all off
hold Holo: stops holo movement and turn servos off, but does not turn light off. 00=all stopped
magic panel on. xx=01 to 98, on from 1 to 98 seconds. 00=off, 99=on permanently
magic panel flicker xx=1 to 99 flicker for 1 to 99 seconds. 00= off.
Turns on-board HP1, 2, 3, and all holos (H0) for xx seconds
x=99 is permanently on.
x=0 turns holo off.
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:
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.
Extended "CuriousMarc Teeces" only commands:
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:
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.
Sound Command format
Sound commands sent to the MarcDuino must follow the format:
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
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.
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.
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)
(capital letter O) Random Off
Stop any current playing sound, and cancel random mode.
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:
Scream (bank 6 sound 1)
Faint/short circuit (bank 6 sound 3)
Leia message (bank 7 sound 1)
Short Cantina music (bank 8 sound 1)
Star Wars (bank 8 sound 2)
Imperial March (bank 8 sound 3)
Long Cantina music (bank 8 sound 5)
Disco Star Wars music (bank 8 sound 6)
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:
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:
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.