Adding a custom board to MobiFlight

Adding a custom board

MobiFlight supports adding custom boards (typically a custom PCB with an on-board microcontroller) without having to modify the desktop connector software. By building a custom version of the firmware and adding a .board.json file for your board you can have MobiFlight detect your board, have different maximum device counts, and control when firmware updates get applied to your board.

This wiki outlines the steps required to do this, using a custom radio PCB built around an RP2040 chip as the example.

Step 1: Modifying the firmware

In order for MobiFlight to recognize the custom PCB as a specific type of board you need to compile the firmware with a custom value for the MOBIFLIGHT_TYPE. Add this value within the platformio.ini file within the environment that corresponds to the microcontroller type into section build_flags =:

'-DMOBIFLIGHT_TYPE="Custom Radio"'

Optionally you can modify the MOBIFLIGHT_NAME, which specifies the default name for the board when it is initially detected by MobiFlight. It is done in the same way as MOBIFLIGHT_TYPE by adding MOBIFLIGHT_NAME in the same section of the platformio.ini file:

'-DMOBIFLIGHT_NAME="Custom Radio"'

If both are added, it should look like:

build_flags = 
	${env.build_flags}
	'-DMOBIFLIGHT_TYPE="Custom Radio"'
        '-DMOBIFLIGHT_NAME="Custom Radio"'
	-I./_Boards/Atmel/Board_Mega

In addition the #define values for the various input/output types can be modified within the MFBoards.h file which belongs to your type of board, e.g. to increase the number of available buttons or LCD displays.

If you want to disable a complete device to reduce the memory consumption, you have to add an additional #define in the platformio.inifile. For e.g. disabling the stepper support you have to add -DMF_STEPPER_SUPPORT=0. Your section build_flags will then look like:

build_flags = 
	${env.build_flags}
	'-DMOBIFLIGHT_TYPE="Custom Radio"'
        '-DMOBIFLIGHT_NAME="Custom Radio"'
        -DMF_STEPPER_SUPPORT=0
	-I./_Boards/Atmel/Board_Mega

Step 2: Setting the firmware version

If you are manually building the firmware locally for distribution you should force the version number of the firmware to something other than the default by modifying the get_version.py file to specify an explicit version number. The version number should be at least 2.4.2 so MobiFlight knows the firmware supports regenerating serial numbers, setting the board name, TM1637 displays, and custom devices.

Step 3: Creating a .board.json file for the desktop app

MobiFlight uses .board.json files located in the Boards folder to know what types of boards are supported and how to detect them. Custom PCBs should create a new .board.json file with the settings necessary for the custom board.

Since the board in this example is based on an RP2040 chip, create a copy of the raspberrypi_pico.board.json file and call it custom_radio.board.json. Then edit the file and change the MobiFlightType entry to match the value specified in the firmware:

    "MobiFlightType": "Custom Radio",

You can also modify the ModuleLimits values to match whatever increased device limits were compiled into the firmware.

Don't forget to change the LatestFirmwareVersion to match the version number set in step 1.

Step 4: Testing it all out

To test this all works put a copy of your custom board.json file in the Boards folder of the connector on the desktop. Put the firmware in the firmware folder. Connect your custom PCB then run MobiFlight.

If there is no custom firmware on the custom board yet MobiFlight should report an ambiguous device connected. Then, in the modules dialog, you should be able to right click on the board and select Update firmware which will display Custom Radio as one of the options.

If the board already has the firmware installed on it MobiFlight should detect it and automatically show it as a Custom Radio board in the modules dialog.

Additional details

Boards without MobiFlight firmware installed are detected based on the VID/PID of the board. The list of valid VID/PIDs used to identify your board are defined in the .board.json file and can be modified by editing the HardwareIDs property in the file. Since all boards that use the same microcontroller will have the same VID/PID this means your custom PCB will be detected as an ambiguous device the first time it is used with MobiFlight.

To avoid this and give your users the best initial experience it is best practice to ship your boards with your custom firmware pre-installed. Boards that have MobiFlight firmware already installed are detected using the MobiFlight Type value instead of the VID/PID. With the custom firmware pre-installed and the correct .board.json file added to the Boards folder, MobiFlight will automatically know your board is custom and will use the custom values from the board file when connected.