[for discussion] Allow to define custom boards and FPGAs.

[zapta]

TL'DR, allow the user to have custom boards.json and fpgas.json in the project, replacing the current flags such as --size and --pack.

This is somewhat related to issue 357 which deals with eliminating the command line flags such as --board, --size, and --pack and making apio.ini the required and the source of truth.

The idea here follow's PIO's way of customizing board definitions, linking scripts and so on. Instead of having a large number of overriding flags in pio.ini, the user can simply add their custom boards or ld file in the project and pio picks it instead of the stock ones.

https://github.com/FPGAwars/apio/blob/develop/apio/resources/boards.json
https://github.com/FPGAwars/apio/blob/develop/apio/resources/fpgas.json

More specific to apio:

1. The flag board will stay in apio.ini as it's now but will got away from the command line.
2. The flags such as --pack and --size will go away and will not move to apio.ini.
3. User will be able to add to their project a boards.json and/or fpgas.json and they will be picked instead of the ones from apio/resources
4. The local files can be small and include only the definitions the user cares about.
5. A warning or an info message will indicates that a local custom file was picked.

Rationale,

1. The format of boards.json and fpgas.json are friendly enough to user that customize boards.
2. The existing boards.json and fpgas.json can be used as a baseline for easy customization.
3. User's will be able to share custom files or submit them as an addition to the stock apio.
4. Code simplicity. Only the file selection is affected.

Cons,

1. If users (icestudio?) construct programmatically a custom configuration on the fly, they may need to create also a boards.json and/or fpgas.json files instead of stuffing everything in apio.ini

Juan, any thoughts? I can work on it as part of the transition.

[Obijuan]

I will answer all your pending questions when I finish releasing Icestudio 0.12. Once it is done, we will start a new cycle and we can rethink apio/icestudio
Give me some weeks to finish the release

[zapta]

Sounds good. Ping me when you will be ready.

For Apio, I believe that Platformio provides a simple and proven model. Down the road, it would be great to have also a Visual Studio Code plugin that takes care of the installation and software update, similar to Platformio.

[zapta]

Hi Juan,

Any thoughts on have APIO searching for boards.json first in the project page? This will allow users to use custom boards, like the one below (a custom upduion31 with FT2232 USB interface) without having to add command line args. I can implement it.

(That custom board is too nichey IMO to be added to the standard boards.json)

{
  "upduino31c": {
    "name": "UPduino v3.1c",
    "fpga": "iCE40-UP5K-SG48",
    "programmer": {
      "type": "iceprog"
    },
    "usb": {
      "vid": "0403",
      "pid": "6010"
    },
    "ftdi": {
      "desc": "UPduino v3.1c"
    }
  }
}

[zapta]

@Obijuan, any thoughts?

[zapta]

Sent for review a pull request that implements this feature.

#393

[zapta]

The feature is submitted and will be included in next APIO release. Currently it is enabled for boards.json and fpga.json. If you add boards.json and/or fpga.json files in your project directory, APIO will use them instead of the built in ones. Typically the custom files contain only the definitions that are actually used in the project but this is not requirement.

The stock boards.json and fpga.json can be found here https://github.com/zapta/apio_dev/tree/develop/apio/resources and can be used as a starting point for the custom files.

In the example, this boards.json file defines an upduino3.1 with an FT2232 programmer instead of the standard FT232. The regex desc matches the custom id string that is programmed into the FT2232 IC. The vid and pid are the standard FT2232 USB vendor and product identifiers.

{
  "upduino31c": {
    "name": "UPduino v3.1c",
    "fpga": "iCE40-UP5K-SG48",
    "programmer": {
      "type": "iceprog"
    },
    "usb": {
      "vid": "0403",
      "pid": "6010"
    },
    "ftdi": {
      "desc": "UPduino v3\\.1c"
    }
  }
}