Extend EZB Protocol

Expanding the capabilities of your robotic projects with Synthiam's ARC platform is made possible through the innovative use of the EZB Protocol Command 0, specifically designed to extend EZBs with new custom functionality. This unique command is a foundational gateway for introducing custom functionalities into the EZB firmware, empowering users to transcend beyond the standard suite of commands. By leveraging this protocol, enthusiasts and developers alike can craft bespoke commands tailored to their specific needs, thus unlocking a new realm of possibilities. Through detailed examples and comprehensive guides, from DJ's UNO Firmware enhancements to the advanced Balance Robot project, the pathway is clear for those aspiring to create or enhance robot skills. This initiative fosters creativity and broadens the scope of what can be achieved, ensuring that your robotic endeavors are limited only by imagination.

To add new functions to the EZB firmware for the Arduino Due/Mega, you can use the EZB Protocol Command 0, also documented in some firmware examples as CmdOurCustomCmds (Command 0). This is a starting point for creating custom commands. The EZB Command 0 is unused for the standard built-in commands of ARC (i.e., moving servos, reading/writing digital I/O, etc.), so it is a designated area in the firmware for user-defined commands, which helps avoid conflicts with existing or future ARC commands.

Several examples of extending the standard EZB Communication Protocol with custom commands exist. Please use these examples as a reference when building your custom EZB firmware...

Creating a custom robot skill will most likely be necessary to send the commands to your new firmware EZB device. You can use the Create Robot Skill Tutorial to learn how to create a robot skill.

This live hack video by DJ Sures has plenty of good information as he creates a robot skill and extends the EZB protocol with new commands. This example demonstrates how to write and read from the protocol with custom commands. It is a long video, but you can skip through sections to find relevant lessons.


Here's a step-by-step guide on how to define new custom command functions in the Arduino Mega EZB firmware:

  1. Identify the Custom Command Range:

    • Ensure that the custom command numbers you choose do not conflict with existing commands in the firmware. Defining a range of numbers for your custom commands unique to your project is a good practice. Adding your custom commands under the EZB Protocol Command 0 will prevent conflict with existing EZB commands documented in the protocol datasheet.

  2. Modify the Firmware:

    • Open the Arduino Mega EZB firmware source code in the Arduino IDE or your preferred development environment.
    • Locate the section of the code that handles the CmdOurCustomCmds command.
    • Define your custom command numbers as constants or enums for better code readability. For example: 
      const byte CmdCustomAction1 = 1;
const byte CmdCustomAction2 = 2;
// ... and so on
    • Add additional else if statements within the CmdOurCustomCmds block to handle your new custom commands. For example: 
      } else if (cmd == CmdOurCustomCmds) {
  byte cmd2 = ReadByte();
  if (cmd2 == CmdCustomAction1) {
    // Handle custom action 1
  } else if (cmd2 == CmdCustomAction2) {
    // Handle custom action 2
  }
  // ... additional custom commands
}
    • Implement the functions that correspond to each custom command. These functions will contain the logic for the actions you want to perform when the command is received.

  3. Compile and Upload the Firmware:

    • After adding your custom commands and their corresponding functions, compile the firmware.
    • Upload the compiled firmware to your Arduino Mega.
  4. Update Your ARC Skill:
    • In your ARC skill, update the code to send the custom commands to the Arduino Mega. Use the CmdOurCustomCmds command followed by the specific custom command number you defined.
    • For example, to send CmdCustomAction1, you would send a packet with CmdOurCustomCmds followed by  CmdCustomAction1.

  5. Testing:

    • Test your ARC skill to ensure that the custom commands are being sent correctly and that the Arduino Mega is responding as expected.

Regarding the number range for custom commands, there isn't a specific range reserved for user-defined commands. However, choosing numbers that are not already in use by the firmware and are unlikely to be used in future updates is essential. Using sub-commands under CmdOurCustomCmds is a good approach, as it organizes your custom commands under a single parent command and reduces the likelihood of conflicts.

Remember to document your custom commands and maintain a list of them to ensure that you don't accidentally reuse numbers for different functions in the future.