Firmata: Creating Custom Boards

This is part of a serial of blogs called Creating Custom Boards. It focuses on adding your own custom boards to a variety of software options.

Over the past year I have spent a lot of time porting different libraries to the Robo HAT MM1 board developed by Robotics Masters. This has lead to discovering a lot about these libraries, how they work behind the scenes and most importantly - what to do to add new boards in the future.

This part of a series of write-ups I will be doing to help others who wish to port libraries for their boards. Many of the sources of information can be vague or difficult for outsiders to understand. I hope to ‘demystify’ and explain how to achieve a successful port for everyone.

Today, we will be looking at the Firmata used by Arduino.

This guide will help you add your board to Firmata so that the underlying protocol can be used in a number of projects with any custom board.

What is Firmata?

I only recently came across Firmata when someone asked me to port it to the Robo HAT MM1. Before then, I had only seen it referenced in the Arduino Examples folder in Arduino IDE. According to the Arduino website, it is described as the below:

The Firmata library implements the Firmata protocol for communicating with software on the host computer. This allows you to write custom firmware without having to create your own protocol and objects for the programming environment that you are using.To use this library#include <Firmata.h>

So it is a library implementing a protocol that is common to a number of different environments. There was a little bit more information on GitHub.

Firmata is a protocol for communicating with microcontrollers from software on a computer (or smartphone/tablet, etc). The protocol can be implemented in firmware on any microcontroller architecture as well as software on any computer software package.

That's about as much research as I did before cracking on with adding another board! So let's get to it!

Before You Begin

Firmata for Arduino makes it SUPER EASY to to port your board. All you need to know is what processor model variant you are using (SAMD51, SAMD21, etc) and the rest should be straight forward.

Heads up at this point! You know what really makes it straight forward for Firmata... adding your board to Arduino IDE first!! You need to do the Arduino IDE: Creating Custom Boards before you can proceed. Without Arduino support you cannot port your board to Firmata.

Once you have completed and test the Arduino IDE software plus got all the information you need about the processor you are using, you can start to look at the software and modify it to work for your custom board.

Let's Begin!

The developers of Firmata have provided no documentation for adding extra boards in their own existing documentation that is publicly available. It all had to be guessed based on past experiences.

Summary:

• Pre-Requisites: Arduino IDE installed, Custom Board Installed (above)
• Fork and Clone repository
• Update File - Boards.h
• Testing
• Pull Request

Each step will be explained in detail below.

I used Windows 10 for all these instructions, but I believe they are platform independent.

Step 1: Fork and Clone Repository

If you plan on adding your board or not to the existing Firmata library, you will need to Fork it. You can do this on GitHub.

After you have forked the library, the only file that you will need to change is boards.h. All other files do not need to be touched. The repository is below:

https://github.com/firmata/arduino

We will update the file at the end of this tutorial. For now, all we need to do is edit the boards.h file from your computer locally (in the Arduino folder - explained below).

Step 2: Update Boards.h

The file we need to edit today is in the Arduino/libraries/Firmata folder. This will be in a different location depending on what operating system you are using and where you installed Arduino IDE. By default on Windows this is in C:\Program Files (x86)\Arduino\libraries\Firmata.

There is a file in this folder called Boards.h. Open it with your text editor.

There is a large amount of intrinsic documentation in this file, however, for the purpose of simplicity we are going to ignore it and jump down to the first board(s).

What you see here is the first three boards defined for Firmata. Each board has a number of different parameters set. At first glace it is not clear where these come from... it took me a while to figure it out. When you open up your custom board's files it becomes clearer. Let's look at all these files side by side.

From boards.txt we get the build identifier.

From variants.h we get the total number of pins and total number of analog pins.

From variant.cpp we get all the pin numbers from the PinDescription array. The numbers in Boards.h correspond to the position in the array.

By now you should be able to see that creating a board in Arduino IDE is very closely linked with the Firmata Firmware.

After reviewing all the above images, you should be able to make the changes you need to add your board. Make sure you add it at the end of the board list just above the #else block. Copy an existing board and edit from there.

Template / Example - Robo HAT MM1

// Robo HAT MM1
#elif defined(ROBOTICSMASTERS_ROBOHATMM1_M4)
#define TOTAL_ANALOG_PINS       7
#define TOTAL_PINS              46 // 14 digital + 7 analog + 4 i2c + 6 spi + 4 serial
#define TOTAL_PORTS             3  // set when TOTAL_PINS > num digitial I/O pins
#define VERSION_BLINK_PIN       LED_BUILTIN
//#define PIN_SERIAL1_RX          0 // already defined in zero core variant.h
//#define PIN_SERIAL1_TX          1 // already defined in zero core variant.h
#define IS_PIN_DIGITAL(p)       ((p) >= 0 && (p) <= 13)
#define IS_PIN_ANALOG(p)        ((p) >= 14 && (p) < 14 + TOTAL_ANALOG_PINS)
#define IS_PIN_PWM(p)           digitalPinHasPWM(p)
#define IS_PIN_SERVO(p)         (IS_PIN_DIGITAL(p) && (p) < MAX_SERVOS) // deprecated since v2.4
#define IS_PIN_I2C(p)           ((p) == 21 || (p) == 22) // SDA = 21, SCL = 21
#define IS_PIN_SPI(p)           ((p) == SS || (p) == MOSI || (p) == MISO || (p) == SCK) // SS = A2
#define IS_PIN_SERIAL(p)        ((p) == 0 || (p) == 1)
#define PIN_TO_DIGITAL(p)       (p)
#define PIN_TO_ANALOG(p)        ((p) - 14)
#define PIN_TO_PWM(p)           PIN_TO_DIGITAL(p)
#define PIN_TO_SERVO(p)         (p) // deprecated since v2.4

Step 3: Testing

After you have added your board, you should be able to upload some test Firmata to it via Arduino IDE. Open up Arduino IDE and select the "FirmataStandard" from the Examples.

You should not need to do anything to this example. Upload it to your board using the normal procedure. You should see "Done uploading." when it is completed.

Your board LED should blink a number of different times if it is successfully running. This blinking sequence shows the version of the Firmata firmware it is running.

The next think to do is to download and install some software to test the firmware with. I opted for https://github.com/MrYsLab/pymata4 which someone kindly pointed me towards. It is a Python based library that interacts with Firmata. You could use something else.

Step 3B: Installing Test Library

Download from GitHub (or clone):

git clone https://github.com/MrYsLab/pymata4

Install the Library with pip:

cd pymata4
pip3 install -e .

Run some examples to see if Firmata is working. I opted to use IDLE for this process just in case Windows starting playing funny games with me.

As you can see, this particular library is able to automatically scan for the correct COM port. Others may not do this. Here is a video of the above example running.

Conclusion

At this point, if the examples all run fine, you have successfully ported Firmata to your custom board! I have not had much time to play with the full power of Firmata but from what I am told, it has a lot of potential.

Make sure that you Pull Request (PR) the main Firmata repository once you are done so that you can have your board included for everyone.

Let me know your thoughts and ideas below. Or if there is a custom boards tutorial you would like to see let me know.

Thank you for reading my tutorial.