How to setup a custom device

Note

This article is for developers who would like to create their own custom device implementation. If you are interested in simply using custom devices, check out this page

Prerequisites

• MobiFlight firmware development is done with VSCode and the PlatformIO extension. Make sure to install both.
• Fork the firmware repository*
• Create a new branch for your custom device.
• Open a terminal window in VSCode and type pio run. This will download all existing Custom Devices into the folder ./CustomDevices and compile each environment defined in the platformio.ini. This has to be done just once. On each next compile this folder get's updated.

Follow the next steps carefully!

Note

If your pio run fails, it is most likely due to the 260 characters filename limitation on Windows. Open git bash with administrative rights and set the following git config: git config --system core.longpaths true and re-run pio run.

Preparing the firmware

1. A new folder under /CustomDevices is required. The foldername should be your (company)Name. This helps to have a better overview between multiple custom device from different users.
2. Copy the _template folder into your newly created folder from step 1 and rename this folder to your device name.
3. Do not rename MFCustomDevice.cpp/.h as these filenames are required from the existing code.
4. Rename MyCustomClass.cpp and MyCustomClass.h to a name which fits to your custom device.
5. Rename MyCustomDevice_platformio.ini to a name which fits to your custom device (see step 3) but keep _platformio.ini, e.g. YourChangedName_platformio.ini
6. Change the include path's from MyCustomClass.cpp and MFCustomDevice.h from #include MyCustomClass.h to #include YourChangedName.h
7. Adapt the YourChangedName_platformio.ini:
   1. Decide which board should be supported. The _template is set up for the Mega and Pico. If one of them is not needed, delete the part which is called in the following environment.
   2. Rename each required environment from [env:mobiflight_template_mega] to your custom device. It should be like [env:YourName_YourCustomDevice_board]
   3. Change -I./CustomDevices/_template under build_flags to your chosen folder name for all environments.
   4. Change +<../CustomDevices/_template> under build_src_filter to your chosen folder name for all environments.
   5. Change '-DMOBIFLIGHT_TYPE="Mobiflight Template Mega"' to your needs. It should be like '-DMOBIFLIGHT_TYPE="YourName_YourDevice_board"'. This is important and this must match with "MobiFlightType" within the .json files (see below)
8. Adapt the platformio.ini:
   1. Add your YourChangedName_platformio.ini under extra_configs = with the complete path, like ./CustomDevices/YourFolderName/YourDeviceNameFolder/YourChangedName_platformio.ini

If you are done, it should look like this:

Now it's time to test all these settings. Open a teminal window in PlatformIO and type pio run. This will compile all environments defined in platformio.ini including your newly defined environments. If everything is setup correct, no failure should be reported. If you only want to compile your new environment, type pio run -e YourName_YourCustomDevice_board (see 7.ii).

Setting up the connector files

custom.board.json files

To get your new defined board recognized from the connector, for each supported board a board.json file has to be set up. Within the copied folder is a sub folder named connector_files. Rename both board.json files to your needs. It should be like YourName_YourDevice_board.board.json. Both files (or just one if only one board should be supported) must be modified:

• change "FirmwareBaseName": "mobiflight_template_raspberrypico" to your defined environment, see point 6.
• change "FriendlyName": "Mobiflight Template Mega" to your needs. This will show up as name of the board in the Mobiflight Modules. This can be get overwritten within this dialog.
• change "MobiFlightType": "Mobiflight Template Mega" to the type you have defined in the YourChangedName_platformio.ini under 6.V. This must match the Type you have defined under 6.V. Otherwise the connector will not find your custom board!
• change "CustomDeviceType": ["MOBIFLIGHT_TEMPLATE","MOBIFLIGHT_TEMPLATE"] to your custom device type(s). If only one type is supported, delete the second entry. These definitions are used to filter the list of custom devices which are under /devices, so only custom devices can be added which fit to the custom firmware. This/these entry(ies) must match "Type": "MOBIFLIGHT_TEMPLATE" within the .device.json file. (* delete/adapt the list of pins if required. E.g. if you have setup an OLED with hardware SPI connection, the pins are predefined by the processor. So these pins would be deleted in this board.json file and would not be in the list of required pins in your device.json file (see below).) -> TBD

custom.device.json files

For each custom device which will be supported a device.json file has to be setup. For the first one rename mobiflight.template.device.json to e.g. YourName.YourDevice.device.json and change the entries to your needs:

1. "Type": "MOBIFLIGHT_TEMPLATE" must match one of the definitions from "CustomDeviceType": ["MOBIFLIGHT_TEMPLATE","MOBIFLIGHT_TEMPLATE"] (only two or more entires if you support two or more custom devices) within the board.json file you have set up. This information is part of the complete definition of the custom device which is stored in the EEPROM. Additionally check this in your code within MFCustomDevice.cpp to prevent a wrong custom device getting loaded and not supported by your software. See the example in MFCustomDevice.cpp which got copied in the steps before. You can find an exemple on how to read this information from the EEPROM in MFCustomDevice.cpp.
2. Define all pins you require for your device. These pins with the hints will show up in the dialog from the UI if you add a custom device to your configuration. Within MFCustomDevice.cpp the pins will be read from the EEPROM for your further use. There is an example in this file how to do this.
3. Define all messages you need for your custom device. These messages can be chosen within the output ConfigWizard under the display tab to choose which value will be sent to which message type. The description entry will also show up to give additional hints what the user should choose.
4. Rename "Label": "Mobiflight's template", to your needs. This label will show up if you add a custom device within the connector

All .json files

1. Copy the xy.board.json files to the /Boards folder and the xy.device.json files to /Devices. Both folders are subfolders from your Mobiflight installation.
2. Copy firmware from .pio/build/YourEnvironmentName/YourEnvironmentName_0_0_1.hex or/and .uf2 to /firmware folder. You can do a right click on the .hex or .uf2 file and choose "Reveal in File Explorer" to open the folder with the file explorer. If you are done, it should look like this:

Testing

Now it's a good point to test everything you have set up. The existing firmware itself will do nothing, but you can check if your new custom board shows up under the Mobiflight Modules dialog when flashing the firmware to your new board. Additionally you can check if your custom device can be selected and uploaded to your board. A new Mega w/o firmware is connected:

In the list of firmwares there should be an entry which matches '-DMOBIFLIGHT_TYPE="YourName_YourDevice_board"' from YourChangedName_platformio.ini. Choose this entry and your firmware gets uploaded. After this step you should be able to add a custom device.

For each YourName.YourDevice.device.json a list item with "Type": "YourName_YourDevice" should show up. Choose one of them and check if all pins show up. If you have more than one custom device defined test this with all of them.

Implement your custom firmware

See all hints in the files. It is also a good idea to check how the examples are set up. The basic GNC255 custom device supports an 256x128 OLED, so just one custom class is supported. The custom device for the FCU and EFIS display from KAV simulation supports two different classes, so it's a good example how to set up two ore more supported devices.

Further information

Special message

There are some special messages with their respective IDs defined:

• Stop message (-1) - The device should turn off on receiving this message. The message is sent by the Connector any time the MobiFlight execution stops (Stop-button) or the application is shutdown.

PowerSavingMode message (-2) - The device should go into a power saving mode (value=1) or wake up from it again (value=0).

Overview how the json files are related

Firmware version

See the additional hints for setting up the firmware version.