How to set up a custom device

First of all, it is assumed that you have properbly installed PlatformIO under VSCode. If not, it is the right time to do this. Next fork the firmware reposority and create a new branch for your custom device. Once this is done, type pio run in the terminal window. This will download all existing Custom Devices into the folder ./CustomDevices and compile each environment definded in the platformio.ini. This has to be done just ones. On each next compile this folder get's updated. Follow the next steps carefully!

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. Is one of them is not needed, delete this 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 choosed folder name for all environments.
   4. change +<../CustomDevices/_template> under build_src_filter to your choosed 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 want only 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 are available, 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 ore more entires if you support two or more custom devices) within the board.json file you have set up. This information is part of of the complete definition of the custom device which is strored in the EEPROM. Additionally check this in your code within MFCustomDevice.cpp to prevent that a wrong custom device gets loaded which is not supported from your software. See the example in MFCustomDevice.cpp which got copied in the steps before. Within MFCustomDevice.cpp is an example, how to read this information from the EEPROM.
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 choosen 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 will show up under the Mobiflight Modules dialog if flashing the firmware to your new board. Additionally you can check if your custom device could be choosed and gets 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 will show up. If you have more than one custom device defined test this with all of them.

Setting up 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 supprted devices.

Overview how the json files are related