Skip to main content

Dashboard Firmware Updates

Dashboard firmware updates​

At farm-ng, we are regularly updating and improving our firmware as we continue to develop the Amiga platform. We want to get every new feature, performance improvement, and reliability increase out to you as soon as we can. And we want to enable you to easily upgrade your dashboard with these improvements at your convenience.

Where to start​

To update the Amiga application layer (our frequent amiga-dash FW releases), you can follow either:

To update the (infrequent) CircuitPython build releases, please follow UF2 bootloader update instructions.

Over-the-air (OTA) Amiga application updates​

You can use the over-the-air (OTA) firmware update method to wirelessly update your amiga dashboard applications from the touchscreen. The Updator app is installed alongside the Dashboard app, starting with the amiga-dash-v0.1.1 release.

info

To begin the Over-the-air (OTA) Amiga application updates, navigate to the ID page of the settings tab.

Do not Mount Circuitpy or have the debug cable or service cable plugged into the dashboard when you launch the updator app! Please stick to one firmware update method.

Please follow the instructions based on the version of Dashboard and Updator apps you have installed.

You should check the versions on the ID page of the settings tab after you update. Keep in mind that your Updator app version may not match your Dashboard app version, and that is OK!

You have the latest Updator app installed!

tip

You can navigate out of the Updator app by power cycling the dashboard.

Just don't power cycle during the final install step! During the download is fine.

Wired Amiga application updates​

To upgrade your Dashboard with the latest Amiga application, grab your Dashboard and your debug cable and take the following steps:

info

This process is currently only supported on Windows and Mac.

To upgrade your Dashboard with the latest Amiga application, grab your Dashboard and your debug cable and take the following steps:

caution

It is required to have a data USB-C cable and not a charge only USB-C cable when connecting to the debug or service cable.

Access the files​

  1. Download the latest application zip file amiga-dash-v0.5.0.zip
  2. For more details on the git latest release navigate to Release: amiga-dash-v0.5.0
  3. Extract the files from the zipped folder
tip
  • Check out the amiga-dev-kit Releases page, as there may be an even newer available release.
  • Select the newest amiga-dash-v#.#.# and download that version.
    • Do not select a fw-dash-v#.#.# or pendant-v#.#.# update!

Connect to your dashboard​

info

If you don't have a debug cable or service cable, reach out to us using one of the options on our For Developers page.

  1. Power down your dashboard.
  2. Connect your debug cable or service cable into the Debug port on the back of the dashboard.
    1. If using a debug cable, connect your Windows or Mac PC to the USB interface:
      1. On newer cables this is the side labelled USB
      2. On older cables this is the larger purple board
    2. If using a service cable, you only have the one port.
  3. Reconnect your dashboard to power

    1. With very early versions of firmware, a folder automatically pops up under the name CIRCUITPY and resembles the example below.

    2. With versions v0.1.8 and higher, there is a Mount CIRCUITPY advanced user button that'll reboot the dashboard and mount it for Windows or Mac computers.

    3. With older versions, you'll need to manually bring the CIRCUITPY drive up on your Windows or Mac computer by:

      1. Open a serial console connected to the dashboard
      2. Interrupt the program with ctrl+C
      3. Run the following commands in the REPL:
      tip

      You can copy code blocks on this website by left clicking the icon in the top right corner of the code block. Paste the commands in the REPL by right clicking and selecting Paste.

      import boot_utils
      boot_utils.mount_circuitpy()

      :::caution If you receive an AtributeError: ModuleNotFound 'mount_circuitpy' error You don't yet have that utility available with your installed dashboard version. To mount the circuitpy drive, you can instead run:

      import os
      import storage
      import microcontroller
      storage.remount("/", False)
      os.remove('boot.py')
      microcontroller.reset()

      ::: 4. The serial console should freeze / exit and the CIRCUITPY drive should now show up mounted

CIRCUITPY mounted​

CIRCUITPY

Update the firmware​

  1. Select all files in the mounted CIRCUITPY drive and delete them
  2. Drag and drop all extracted files from the downloaded firmware update.
    1. Make sure to drop all files (dashboard/, updator/, node_id.txt, code.py, boot.py, etc.) directly into the root of the CIRCUITPY drive (as below).
      1. The firmware will NOT load if the files are nested in a subfolder.
  3. Once the file transfer is complete, power cycle your dashboard (disconnect & reconnect power) and check the basic functionality.
    1. The dashboard will no longer mount as CIRCUITPY when connected to a computer. If you have any issues, go through the connecting / mounting process again OR see the troubleshooting information below.
  4. If all is as expected, you're good to go. Just power down the dashboard, disconnect the debug cable, and enjoy your new features!
  5. [Recommended] Navigate to the configuration tab (gear icon) on the dashboard, and select the pendant icon to calibrate your pendant and confirm functionality.
  6. [Recommended] Also check the settings and ensure your desired wheel track and turning speed values remain.

CIRCUITPY_updated_windows

Troubleshooting
  • If the file transfer process fails, or the behavior is not as expected, just delete all files in CIRCUITPY and try it again.

    • If the dashboard remounts on your computer as CIRCUITPY, just select all and delete.

    • If the dashboard does NOT remount on your computer as CIRCUITPY:

      import storage
      storage.erase_filesystem()
      # The dashboard should reboot automatically
      # If it does not, continue with:
      import microcontroller
      microcontroller.reset()
      • This will reset the microcontroller to a "hello world" state and it should remount as CIRCUITPY.
      • You can now manually delete all files and try again.
  • Repeated hot plugging / unplugging of the dashboard can cause the filesystem to go into an irregular state. Try connecting / disconnecting between dashboard and your PC with the dashboard powered down.
  • When in doubt, turn it off and back on again.

UF2 bootloader update​

Overview​

Occasionally, it may be recommended to update the bootloader UF2 firmware installed on your dashboard. At farm-ng, we generate a custom UF2 file for our dashboards that are tailored towards the dashboard's use case. For example, we've increased the capacity of the receive queue for the CAN module, which reduces the likelihood of dropped messages!

The farm-ng UF2 releases may come out following a CircuitPython stable release, or if we find more modifications that significantly improve performance or enable new features.

To learn more about the topic of UF2 bootloader files, Adafruit UF2 details is a great place to start!

info

This process is currently only supported on Windows and Mac.

Access the files (UF2)​

  1. Download the latest fw-dash UF2 file
    1. For more details on the UF2 file release see the release page here: Release: fw-dash-v1.1.0

Connect to your dashboard (UF2)​

  1. Power down your dashboard.
  2. Connect your debug cable or service cable into the Debug port on the back of the dashboard.
    1. If using a debug cable, connect your Windows or Mac PC to the USB interface:
      1. On newer cables this is the side labelled USB
      2. On older cables this is the larger purple board
    2. If using a service cable, you only have the one interface.
  3. Reconnect your dashboard to power so a folder automatically pops up under the name CIRCUITPY, as with the farm-ng firmware update example above.

Load into BOOTLOADER mode​

  1. With the dashboard connected to your PC, load into BOOTLOADER mode so the dashboard remounts under the name AMIGA and resembles the AMIGA mounted example below:

    1. With versions v0.1.8 and higher, there is a BOOTLOADER advanced user button that'll reboot the dashboard into BOOTLOADER mode.

    2. Otherwise, if using a debug cable you can double click the reset button.

    3. Otherwise, if using a service cable (or if you can't seem to get the double click timing right):

      1. Open a serial console connected to the dashboard
      2. Interrupt the program with ctrl+C
      3. Enter the following commands in the REPL:
      import boot_utils
      boot_utils.reset_to_bootloader()

      :::caution If you receive an AtributeError: ModuleNotFound 'reset_to_bootloader' error You don't yet have that utility available with your installed dashboard version. To load into BOOTLOADER mode, you can instead run:

      import microcontroller
      microcontroller.on_next_reset(microcontroller.RunMode.BOOTLOADER)
      microcontroller.reset()

  2. Drag and drop the newly downloaded UF2 file onto the mounted drive.

  3. This will immediately cause the bootloader firmware to update, and the dashboard will automatically reboot as CIRCUITPY once complete.

note

The Amiga application layer should remain untouched, so be sure to update that if it is not already up to date!

AMIGA mounted​

AMIGA

Troubleshooting

In rare cases, the board could go into an update failure mode.

In this case, the microcontroller inside the dashboard is restored to the factory default Hello world example. This will be characterized by no display on the dash and no response. You can double check this occurred by opening the file named code.py (or main.py) and seeing that there is only a single line of code print('hello world'). In this case, you should go through both the UF2 firmware and Amiga application updates update steps.