05 ‐ Over the Air (OTA) Updates
After completing the initial upload via USB, it is possible to then update the main .ino file, along with any changes to the Settings or Credential files, via over-the-air (OTA) updates, eliminating the need to power down the controller and reconnect it to your computer via USB. There are a few prerequisites for making this work.
- You must complete the initial upload, with your local settings, via USB the first time
- Your controller must be on local wifi and the source device for sending the update must be on the same network/subnet
- Your network and source device must support and recognize Multicast DNS (mDNS)*
- You need to know the current IP address of the controller (get from router or other tools if you do not have this already)
*The mDNS requirement is a requirement of the Arduino IDE, which will only recognize network ports via mDNS. The most recent builds of Windows 10 support mDNS. If you have an older build or operating system (or if you cannot get the controller port to show up), you may need to install Apple's Bonjour for Windows on the machine where you are using the Arduino IDE.
- Launch the Arudino IDE (or compatible IDE) and open the updated .ino file you wish to upload.
- Verify you have the right board selected
- For the port, select the network port 'ota_host_name at your-controller-ip-address' (ota_host_name is the name you defined in the Settings file)
If you do not see the controller IP address listed under network ports, see the mDNS prerequisites above. You might also try restarting the controller and relaunching the Arduino IDE. I have found that on occasion, the port disappears. But a restart of the controller generally resolves this issue. You may also need to increase the ota_boot_time_window in the settings file (see the Credentials and Settings wiki topic).
- Verify your code via the Arduino IDE to assure there are no errors.
- Open a web browser and enter the IP address of your controller followed by /otaupdate (example: http://192.168.1.215/otaupdate)
- The web browser should return a message that the controller is ready to accept an upload:
- Click the Upload button in the Arduino IDE to upload your new file. If a successful connection is made, the output window of the IDE should show Uploading..........
- After the upload completes, the controller will automatically reboot and execute your new code.
NOTE: If the controller does not beginning receiving data within the time you defined in the Settings file, it will leave the upload mode and return to the previous FM receiver mode. If this happens, simply reissue the browser /otaupdate command to enter the OTA update mode again. Since this window needs to be kept relatively short to avoid watchdog resets, it is recommended that you already have the Arduino IDE open and your code verified and ready to upload prior to putting the controller in update mode.
In addition to uploading code to the controller, you can also remotely issue a reboot or restart of the controller. The reboot will occur within a few seconds of issuing the restart command.
To reboot the controller remotely, simply enter the IP address of the controller, followed by /restart (Example: http://192.168.1.225/restart)
If a new version is released in this repository and you wish to upgrade, read the release notes carefully. If the release does not contain new features that require modifications to the Credentials.h or Settings.h files (this will be explicitely stated in the release notes if new versions of these files are necessary), you should only replace the fm_receiver_mqtt.ino file and not overwrite your existing Credentials.h or Settings.h files. That way, you will maintain all of your connection, credential and setting information. But it may be necessary to reset your client/host options and FM presets if you changed them previously. If a new Credentials.h or Settings.h file is required, the release notes will contain more information on applying those changes.
In the event that something in the new code prevents the controller from successfully booting, fixes obviously cannot be pushed over-the-air. In this case, unless the memory of the board has been corrupted or the board is stuck in an unrecoverable boot loop, it should be possible to reflash it via USB with a known good .ino file. Worst case, you can flash a replacement board with a known good version.