BetterDuino Firmware V4

Estimated reading time: 9 min

Original Github: https://github.com/RealNobser/BetterDuinoFirmwareV4

Important Disclaimer

BetterDuinoFirmwareV4 has nothing to do with the original firmware made by Marc nor with the spinoff made by Neil! So if you have any questions about BetterDuino Firmware V4 don’t ask any of them!

If you find any issues, please use the github “Issues” mechanism. When you are an experienced software developer please feel free to submit pull requests. This is a living repository and I appreciate any community input!

Please do not contact astromech.net or open up a discussion in the astromech.net forum. astromech.net is not in charge with BetterDuinoFirmwareV4. You will not get any support or help regarding BetterDuino. On the other side, if you have questions about the original firmware for MarcDuino boards, then you are fine in the astromech forum.

If there are still questions not anserwed here, feel free to visit Michael Baddeleys fantastic Printed Droid community here: https://www.facebook.com/groups/printeddroid/ or https://www.facebook.com/groups/MrBaddeley .
You will be treated in a fair and polite way and we will find a solution or answer to your questions!

Nevertheless: Read and understand, how the boards work, why there is a master and a slave board, how the boards are connected ->

https://www.curiousmarc.com/r2-d2/marcduino-system

https://astromech.net/forums/showthread.php?28414-Support-Thread-for-MarcDuino-v1-5-s

As soon as you are familiar with MarcDuino, come back here and proceed!

Why a Replacement Firmware for MarcDuino boards?

The last update to the original firmware was in 2018. Neil’s last update was a minor change in mid-2022. His V3 software has about 80% of the original source in common, adding some features for the latest MarcDuino boards (servo controllers and EXT/AUX pin controllers). He also added the nice feature of saving settings to EEPROM at runtime. But the code also has some glitches and bugs and is based on outdated Arduino libraries. I started 2023 after the whole Arduino framework and community has made really great progress in the last 5 years.

The BetterDuino Firmware V4 code has completely been rewritten from scratch. I took Neils idea of the EEPROM storage a step further, so nearly any setting is stored there. Including per-servo position settings. I also added the new panel animation of Tim Hebel who is also using a modified MarcDuino V3 firmware (https://github.com/Eebel/SHADOW_MD_EEBEL).

What is the MarcDuino system?

(from https://www.curiousmarc.com/r2-d2/marcduino-system):

“The MarcDuino system controls the animatronics of an R2 (dome panels, light and sound). It currently controls 10 dome panels, an “MP3 Trigger” sound board, dome “Teeces” lights and holoprojectors light and movements, and I2C gizmos you can add-in yourself. It has lots of pre-programmed effects making all these act together.

The system is centered around the MarcDuino boards which sit in the R2. There are two kinds, the Master and the Slave board, which are very similar to each other.” – CuriousMarc

What is BetterDuino Firmware V4?

The BetterDuinoFirmwareV4 software is a firmware replacement for the original MarcDuino V1.5Rev3 boards.

Details about the boards can be found here:

https://www.curiousmarc.com/r2-d2/marcduino-system/marcduino-boards/marcduino-v1-5

https://astromech.net/forums/showthread.php?28414-Support-Thread-for-MarcDuino-v1-5-s

The original firmware can be found here:

https://www.curiousmarc.com/r2-d2/marcduino-system/marcduino-software-reference

There also is a spinoff of Marcs firmware also known as MarcDuinoMain V3 and MarcDuinoClient V3:

https://github.com/nhutchison/MarcDuinoMain

https://github.com/nhutchison/MarcDuinoClient

New Features (excerpt)

  • Support for MP3 Trigger, DF Mini Player and R2-D2 / Astromech Vocalizer (https://humancyborgrelations.com/)
  • Identical firmware for Master and Slave
  • Automatic configuration of Master and Slave at first startup
  • per servo runtime settings for min/max and open/close positions
  • switch to modern OOP software design and use of most recent common Arduino libraries
  • fixed a lot of bugs at least of the V3 spinoff

Lets get started

Revision History

DateRevDescription
2023-10-23V0.9.0 RC1First version for closed beta test group

Known MISSING functionality compared to the original source (will be released in the future)

  • I2C command support
  • RC-IN support

Supported Boards

BoardSupport
MarcDuino V1.5 Rev3YES
MarcDuino V1.5 Rev2not yet, but planned, tests pending
MarcDuino V1NO
MarcDuino V2NO
BenDuino boards (https://www.printed-droid.com/kb/benduino-system/)YES

Compatibility Matrix

Master/Salve1.83.x4.x
1.8YESYESYES
3.xYESYESYES
4.xYESYESYES

Uploading firmware using *.hex files

Development Environment

Building and uploading firmware using Visual Studio Code

Clone the GitHub repository using Visual Studio Code (Source Control / Clone Repository)

Open local folder

Edit the file “platformio.ini” to match the serial port of your programmer:
upload_port = /dev/cu.usbmodem141201 (example)

build the code (PlatformIO / ATmega328P / General / Build)

upload the code (PlatformIO / ATmega328P / General / Upload)

MarcDuino/BetterDuino Commands

Format

Every command must start with one of these special characters (defined in the header file). The start character is recognized in the main loop:

Master

Start CommandFunctionMasterRemark
:Pie panel commandYESSlave only Subset and for Panel 12/13
*Holo Projector (HP) commandsTO SLAVE via Serial_Slave / suart
@Display commandsTO SLAVE via Serial_Slave / suart
$Sound commandsYES
!Alt1 alternate sound command, passed to suart2 after strippingTO MP3 via Serial_MP3 / suart2
%Alt2 alternate HP board command, passed to suart without strippingTO SLAVE via Serial_Slave / suart
#MarcDuino Setup commands used to configure various settings on the MarcDuinoYES / TO SLAVE (to keep EEPROM in sync)No sync of MarcDuino Type to Slave
&I2C-CommandYES / TO I2C

Slave

Start CommandFunctionSlaveRemark
:Pie panel commandYESSlave only Subset and for Panel 12/13
*Holo Projector (HP) commandsYES
@Display commands, forwarded to JEDI controller on suart1 after stripping the ‘@’ control characterTO TEECES via Serial_Teeces / light_suart / suart / suart1
$Sound commandsNO
!Alt1 alternate display command, passed to suart after strippingTO TEECES via Serial_Teeces / light_suart / suart suart1In normal use the Master MarcDuino catches these, so we don’t see them
%Alt2 expansion command, passed to suart2 after strippingTO MAGIC via Serial_Magic / slave_suart / suart2
#MarcDuino Setup commands used to configure various settings on the MarcDuinoYES

Panel Commands

They must follow the syntax “:CCxx\r” where CC=command , xx= two digit decimal number, \r is carriage return.

CommandFunctionMasterSlaveRemark
:SExxlaunches sequences, see belowYESYES
:OPxxopen panel number xx=01-13. If xx=00, opens all panels (12/13 Slave only)YESYES
:OP14open top panelsYESNOtbd
:OP15open bottom panelsYESNOtbd
:CLxxclose panel number xx=01-13, removes from RC if it was, stops servo. If xx=00, all panels, slow close.YESYES
:RCxxplaces panel xx=01-13 under RC input control. If xx=00, all panels placed on RC.YESNO
:STxxbuzz kill/soft hold: removes panel from RC control AND shuts servo off to eliminate buzz. xx=00 all panels off RC servos off.YESYES
:HDxxRC hold: removes from RC, but does not turn servo off, keeps at last position. xx=00 all panels hold.YESNO

Sequence Command Details

See sequence_command, panel sequence matrices defined in panel_sequences.h

CommandFunctionRemark
Full (Move, Sound, Display…)
:SE00Close all panels (full speed), servo off – use as init only. Use CL00 for all soft close.
:SE01Scream, with all panels open
:SE02Wave, one panel at a time
:SE03Fast (Smirk) back and forth wave
:SE04Wave 2 (open progressively all panels, then close one by one)
:SE05Beep Cantina (with marching ants panel action)
:SE06Faint/Short Circuit
:SE07Cantina dance (orchestral, rythmic panel dance)
:SE08Leia
:SE09Disco
:SE10Quite Mode reset (panel close, stop holos, stop sounds)
:SE11Full Awake Mode reset (panel close, random sound, holo movement, no holo lights)
:SE12Top Panels to RC
:SE13Mid Awake Mode reset (panel close, random sound, stop holos)
:SE14Awake+ Mode reset ((panel close, random sound, holo movement, lights on)
:SE15Screams no panels
:SE16Panel Wiggle
Body Sequences
:SE30Utility ARM open and close sequence
:SE31All Body Panels open and close sequence
:SE32All Body Doors open and wiggle close sequence
:SE33Body – Use Gripper
:SE34Body – Use Interface Tool
:SE35Body – Ping Pong Body Doors
Move Panels only
:SE51Scream, with all panels open
:SE52Wave, one panel at a time
:SE53Fast (Smirk) back and forth wave
:SE54Wave 2 (open progressively all panels, then close one by one)
:SE55Marching ants
:SE56Faint/Short Circuit
:SE57Rhythmic panel dance
:SE58Panel Wave Bye Bye
:SE59Open panels half way

Holo Projector Commands

These commands are only processed by the MarcDuino Slave module

CommandFunctionRemark
*RDxxRandom Holo movement (xx=01 to 03). xx=00 and >3 all random.
*ONxxTurns Holo Light on (xx=01 to 03). xx=00 or >3 all lights on
*OFxxTurns Holo Lights off (xx=01 to 03). xx=00 turns all lights off
*RCxxHolo vertical movement under RC control, horizontal centered (xx=01-03). 00 or >3 all RC
*TExxHolo movement test (xx=01-03). Goes through a loop of holo movements to assist in adjusting holo servos mechanical setup. 00 or >3 all HPs to test
*STxxstop/reset Holos random movement, turns lights off, and RC off. 00=all off
*HDxxhold: stop holo, do not change light level. 00=all stopped
*MOxxmagic panel on. xx=01 to 98, on from 1 to 98 seconds.

* xx = 99 is on permanently

* xx = 00 is off
*MFxxmagic panel flicker xx=1 to 99 flicker for 1 to 99 seconds. 00= off.
*H1xx

*H2xx

*H3xx

*H0xx
Will turn on-board HP1, 2, 3, and all (HP0xx) for xx seconds.

* xx = 99 is on permanently

* xx = 00 is off
*F1xx

*F2xx

*F3xx

*F0xx
Will flicker on-board HP1, 2, 3, and all (F0xx) for xx seconds.

* xx = 99 is on permanently

* xx = 00 is off

Sound Commands

These commands are only processed by the MarcDuino Master module

CommandFunctionRemark
$xyyPlay sound command by bank/sound numbers

* x=bank number

* yy=sound number. If none, next sound is played in.
$xyPlay sound command by bank/sound numbers, short version

* x=bank number

* y=sound number. If none, next sound is played in.
$Crandom from 4 first banks
$Osound off
$LLeia message (bank 7 sound 1)
$CCantina music (bank 9 sound 5)
$cBeep cantina (bank 9 sound 1)
$SScream (bank 6 sound 1)
$FFaint/Short Circuit (bank 6 sound 3)
$DDisco (bank 9 sound 6)
$sstop sounds
$+volume up
$-volume down
$mvolume mid
$fvolume max
$pvolume min
$WStar Wars music (bank 9 sound 2)
$wBeep Star Wars music (bank 9 sound 7)
$MImperial March (bank 9 sound 3)
$iBeep Imperial March (bank 9 sound 8)
$BStartup Sound

Special Features

CommandFunctionRemark
*EOxx

TO SLAVE
Pull pin high/low on AUX1. Can be used to trigger a smoke machine as an example.

xx is the time in seconds.

* 00 – off

* 01-98 is the time in seconds (don’t use values >10 for smoke machines!)

* 99 on permanently (again don’t use for smoke machines)
will be executed on SLAVE only
:EOxxPull pin high/low on AUX1. Can be used to trigger a smoke machine as an example.

xx is the time in seconds.

* 00 – off

* 01-98 is the time in seconds (don’t use values >10 for smoke machines!)

* 99 on permanently (again don’t use for smoke machines)
will be executed on MASTER only

BetterDuino Firmware V4 and greater

Setup Commands

CommandFunctionRemark
Servo Controls
#SD00Set global servo direction forward
#SD01Set global servo direction reversed
#SRxxySet individual servo to either forward or reversed xx=servo number y=direction

* Must be a 2 digit Servo number i.e. Servo 4 is 04

* Must be either 0 or 1 to set the direction (0 normal, 1 reversed)

* Use SDxx to globally set the Servo direction, then SRxxy to change individual servos.
depricated, removed in future releases
#SRxxSet individual servo to reversed, xx=servo number

* Must be a 2 digit Servo number i.e. Servo 4 is 04

* Use SDxx to globally set the Servo direction, then SRxxy to change individual servos.
BetterDuino Firmware V4 and greater
#SNxxSet individual servo to normal, xx=servo number

* Must be a 2 digit Servo number i.e. Servo 4 is 04

* Use SDxx to globally set the Servo direction, then SRxxy to change individual servos.
BetterDuino Firmware V4 and greater
#SVxxUse individual servo settings (0 = no, 1 = yes)BetterDuino Firmware V4 and greater
#SOxxddddSet Servo Degrees/Microseconds for Panel Open, dddd=0000-0180 deg, dddd > 0544 MicrosecondsBetterDuino Firmware V4 and greater
#SCxxddddSet Servo Degrees/Microseconds for Panel Closed dddd=0000-0180 deg, dddd > 0544 MicrosecondsBetterDuino Firmware V4 and greater
#SPxxdddSet Servo Speed, ddd=0-255BetterDuino Firmware V4 and greater
Startup Sound Controls
#SSxxSet startup sound

* #SS00 : Disable Startup Sound, and remove startup sound delay for fast boot of R2

* #SS01 : Default Startup Sound in file 255

* #SS02 : Alternate Startup Sound in file 254

* #SS03 : Second Alternate Startup Sound in file 253
depricated, removed in future releases
#SSxxxSet startup sound

* #SS000 : Disable Startup Sound, and remove startup sound delay for fast boot of R2

* #SSxxx : Set Startup Sound in file xxx
BetterDuino Firmware V4 and greater
#SQxxChatty / Silent mode

* #SQ00 : Default Chatty Mode

* #SQ01 : Silent on startup
#SMxxDisable Random Sound

* #SM00 : Random Sound on
#SM01 : No Random Sound + Volume off
#SM02 : No Random Sound
What’s the difference between Chatty and Random Sounds (#SQxx)?

maybe depricated
#SXxxSet Max Random Pause in seconds. – Maximum timespan between two random soundsBetterDuino Firmware V4 and greater
#SYxxSet Min Random Pause in seconds – Minimum timespan between two random soundsBetterDuino Firmware V4 and greater
Panel Sequencer Controls
#STxxSetup Delay time between Master and Slave Panel Sequence. Use this if the Slave panels are starting too soon. Values up to 250 are supported. Values are in ms.maybe depricated
System Configuration and Management
#MDxxSet MarcDuino Mode

* #MD00 : MarcDuino Dome Master

* #MD01 : MarcDuino Dome Slave

* #MD02 : MarcDuino Body Master


MarcDuino will reboot immediately after setup and start up in new mode.
BetterDuino Firmware V4 and greater
#MPxxSet MP3-Player Type

* #MP00 : SparkFun MP3 Trigger

* #MP01 : DFPlayer

* #MP02 : Vocalizer
BetterDuino Firmware V4 and greater
#MSxyySet maximum sounds per soundbank. x=1-9 (Soundbank), y=0-25 (max. Sounds)BetterDuino Firmware V4 and greater
#HLxySet HoloLight x to High Active (y=1) or Low Active (y=0). x=0 → All Holo Lights
#HOxxddddSet Holo HServo Degrees/Microseconds Max, dddd=0000-0180 deg, dddd > 0544 MicrosecondsBetterDuino Firmware V4 and greater
#HCxxddddSet Holo HServo Degrees/Microseconds Min, dddd=0000-0180 deg, dddd > 0544 MicrosecondsBetterDuino Firmware V4 and greater
#HPxxdddSet Holo HServo Speed, ddd=0-255BetterDuino Firmware V4 and greater
#VOxxddddSet Holo VServo Degrees/Microseconds Max, dddd=0000-0180 deg, dddd > 0544 MicrosecondsBetterDuino Firmware V4 and greater
#VCxxddddSet Holo VServo Degrees/Microseconds Min dddd=0000-0180 deg, dddd > 0544 MicrosecondsBetterDuino Firmware V4 and greater
#VPxxdddSet Holo VServo Speed, ddd=0-255BetterDuino Firmware V4 and greater
#DUxxDump EEPORM to serial

* #DUxx : value at address xx

* #DUMP : dump complete EEPROM content
BetterDuino Firmware V4 and greater
#RSETRestart MarcDuinoBetterDuino Firmware V4 and greater
#ADxxAdjustment Mode: When setting up individual Servo settings, servo will positioned immediately

* #AD00 : Adjustment Mode Off

* #AD01 : Adjustment Mode On
BetterDuino Firmware V4 and greater

EEPROM Memory Map

All the settings of the “Setup Commands” are stored in EEPROM. The corresponding Memory Map is described here. Default settings when EEPROM is empty are written in bold letter.

AddressTypeContentDescription
0x00byteSW-/Config-VersionVersion 4.0.x = 40, Version 4.1.x = 41, …
0x01byteMarcDuinoType0 = DomeMaster

1 = DomeSlave

2 = BodyMaster
0x02byteStartup Sound0 = none

1 = File255

2 = File254

3 = File253

DEPRICATED by Startup Sound Nr
0x03byteChatty/Silent Mode0 = Chatty

1 = Silent
0x04byteMP3-Player-Type0 = SparkFun MP3-Trigger

1 = DF-Mini Player
0x05byteDisable Random Sound0 = Random Sound

1 = No Random Sound + Volume off

2 = No Random Sound

DEPRICATED, collision with Chatty/Silent mode switch
0x06wordSlave DelaySequence Delay for Slave Sequence Start in ms
0x07Slave Delay
0x08Number of Servos
0x09Startup Sound Nrobsoletes “Startup Sound”, default 255
0x0aMinRandomPause in secondsMinimal Pause between two Random sounds played, default 6s
0x0bMaxRandomPause in secondsMAximal Pause between two Random sounds played, default 12s
0x11 – 0x19bytesMax Sound Bank 1-91-25 Songs per Bank, default standard SD-Card-Layout (Bank-Sounds): 1-19, 2-18, 3-7, 4-4, 5-3, 6-3, 7-3, 8-6, 9-8
0x20byteGlobal Servo Direction0 = Normal

1 = Reverse
0x21-0x2dbytesServo1-Servo13 Servo Direction0 = Normal

1 = Reverse
0x30byteGlobal Servo Speed0 = Minumum

255 = Maximum
0x31-0x3dbytesServo1-Servo13 Servo Speed0 = Minumum

255 = Maximum
0x40wordGlobal Servo Open Position Degrees / Microseconds0 = 0 deg

180 = 180 deg

treat values less than 544 as angles in degrees (valid values in microseconds are handled as microseconds)
0x42-0x5awordsServo1-Servo13 Servo Open Position Degrees0 = 0 deg

180 = 180 deg

treat values less than 544 as angles in degrees (valid values in microseconds are handled as microseconds)
0x60wordGlobal Servo Closed Position Degrees0 = 0 deg

180 = 180 deg

treat values less than 544 as angles in degrees (valid values in microseconds are handled as microseconds)
0x62-0x7awordsServo1-Servo13 Servo Close Position Degrees0 = 0 deg

180 = 180 deg

treat values less than 544 as angles in degrees (valid values in microseconds are handled as microseconds)
0x80wordGlobal Servo Mid Position Degree0 = 0 deg

180 = 180 deg

treat values less than 544 as angles in degrees (valid values in microseconds are handled as microseconds)
0x82-0x9awordsServo1-Serv013 Servo Mid Position Degree0 = 0 deg

180 = 180 deg

treat values less than 544 as angles in degrees (valid values in microseconds are handled as microseconds)
0xa0wordGlobal Holo-Servo-H Direction(0-Normal, 1-Reverse)
0xa1wordGlobal Holo-Servo-V Direction(0-Normal, 1-Reverse)
0xa2wordServo1 Holo1-Servo-H Direction(0-Normal, 1-Reverse)
0xa3wordServo2 Holo1-Servo-V Direction(0-Normal, 1-Reverse)
0xa4wordServo3 Holo2-Servo-H Direction(0-Normal, 1-Reverse)
0xa5wordServo4 Holo2-Servo-V Direction(0-Normal, 1-Reverse)
0xa6wordServo5 Holo3-Servo-H Direction (0-Normal, 1-Reverse)
0xa7wordServo6 Holo3-Servo-V Direction(0-Normal, 1-Reverse)
0xb0wordGlobal Holo-Servo-H Min PositionDegree (0-180) / Microseconds (>=544)
0xb2wordGlobal Holo-Servo-V Min PositionDegree (0-180) / Microseconds (>=544)
0xb4wordServo1 Holo1-Servo-H Min PositionDegree (0-180) / Microseconds (>=544)
0xb6wordServo2 Holo1-Servo-V Min PositionDegree (0-180) / Microseconds (>=544)
0xb8wordServo3 Holo2-Servo-H Min PositionDegree (0-180) / Microseconds (>=544)
0xbawordServo4 Holo2-Servo-V Min PositionDegree (0-180) / Microseconds (>=544)
0xbcwordServo5 Holo3-Servo-H Min PositionDegree (0-180) / Microseconds (>=544) 
0xbewordServo6 Holo3-Servo-V Min PositionDegree (0-180) / Microseconds (>=544)
0xc0wordGlobal Holo-Servo-H Max PositionDegree (0-180) / Microseconds (>=544)
0xc2wordGlobal Holo-Servo-V Max PositionDegree (0-180) / Microseconds (>=544)
0xc4wordServo1 Holo1-Servo-H Max PositionDegree (0-180) / Microseconds (>=544)
0xc6wordServo2 Holo1-Servo-V Max PositionDegree (0-180) / Microseconds (>=544)
0xc8wordServo3 Holo2-Servo-H Max PositionDegree (0-180) / Microseconds (>=544)
0xcawordServo4 Holo2-Servo-V Max PositionDegree (0-180) / Microseconds (>=544)
0xccwordServo5 Holo3-Servo-H Max PositionDegree (0-180) / Microseconds (>=544)
0xcewordServo6 Holo3-Servo-V Max PositionDegree (0-180) / Microseconds (>=544)
0xd1wordHolo1 LightHigh Active (=1) or Low Active (=0)
0xd2wordHolo2 LightHigh Active (=1) or Low Active (=0)
0xd3wordHolo3 LightHigh Active (=1) or Low Active (=0)
0xe0wordGlobal Holo-Servo-H Speed(0-255)
0xe1wordGlobal Holo-Servo-V Speed(0-255) 
0xe2wordServo1 Holo1-Servo-H Speed(0-255)
0xe3wordServo2 Holo1-Servo-V Speed(0-255) 
0xe4wordServo3 Holo2-Servo-H Speed(0-255)
0xe5wordServo4 Holo2-Servo-V Speed(0-255)
0xe6wordServo5 Holo3-Servo-H Speed(0-255)
0xe7wordServo6 Holo3-Servo-V Speed(0-255) 
Tags:
Was this article helpful?
Dislike 0 0 of 0 found this article helpful.
Views: 240
Previous: AstroCan Bridge:
Next: Domelift Integration into the ShadowMD system