From be71798836f34d6effdd21ee62b0025c4dc0de98 Mon Sep 17 00:00:00 2001 From: HomeSpan Date: Wed, 17 Feb 2021 08:02:12 -0600 Subject: [PATCH] Update OTA.md --- docs/OTA.md | 22 ++++++++++------------ 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/docs/OTA.md b/docs/OTA.md index 372e821..70b74c2 100644 --- a/docs/OTA.md +++ b/docs/OTA.md @@ -1,30 +1,28 @@ # Over-the-Air (OTA) Updates -HomeSpan supports Over-the-Air (OTA) updates, which allows you to *wirelessly* upload sketches directly from the Arduino IDE. To activate this feature for your sketch, simply call the method `homeSpan.enableOTA()` prior to calling `homeSpan.begin()`. +HomeSpan supports Over-the-Air (OTA) updates, which allows you to *wirelessly* upload sketches directly from the Arduino IDE - no serial connection needed. To activate this feature for your sketch, simply call the method `homeSpan.enableOTA()` prior to calling `homeSpan.begin()`. -When a HomeSpan sketch is run with OTA enabled, the device shows up as a "network" port that can be selected under the *Tools → Port* menu in the Arduino IDE. Once selected, the IDE will direct all uploads to the device via WiFi instead of looking for it on a serial port. Note that you can upload via OTA even if your device is still connected to a serial port, but the Arduino IDE does not presently support multiple port connections at the same time and will automatically close the Serial Monitor upon selecting your device via a network port. +When a HomeSpan sketch is run with OTA enabled, the device shows up as a "network" port that can be selected under the *Tools → Port* menu in the Arduino IDE. Once selected, the IDE will direct all uploads to the device via WiFi instead of looking for it on a serial port. Note that you can upload via OTA even if your device is still connected to a serial port, but the Arduino IDE does not presently support multiple port connections at the same time. If you select a "network" port, the IDE will automatically close the Serial Monitor if it is open. To re-instate uploads via the "serial" port, simply choose that port from the *Tools → Port* menu in the Arduino IDE. Uploading via the serial port is always possible regardless of whether you have enabled OTA for a sketch. -By default, HomeSpan requires the use of a password whenever you begin an OTA upload. The default OTA password is "homespan-ota". The Arduino will prompt you for this when you attempt the first OTA upload after opening the Arduino IDE, after which it will remember the password until the IDE is shut down. +By default, HomeSpan requires the use of a password whenever you begin an OTA upload. The default OTA password is "homespan-ota". The Arduino will prompt you for this password upon your first attempt to upload a sketch to a newly-connected device. However, once the password for a specific device is entered, the Arduino IDE retains it in memory as long as the IDE is running, thereby saving you from having to type it again every time you re-upload a sketch via OTA. You can change the password for a HomeSpan device from the [HomeSpan CLI](CLI.md) with the 'O' command. Similar to a device's Setup Code, HomeSpan saves a non-recoverable hashed version of the OTA password you specify in non-volatile storage (NVS). If you forget the password you specified, you'll need to create a new one using the 'O' command, or you can restore the default OTA password by fully erasing the NVS with the 'E' command. -> :exclamation: Though not recommended, you can override the requirement for a password by enabling OTA with *false* as the parameter as such: `homeSpan.enableOTA(false)`. Use with caution! Anyone who can access the device over your network will now be able to upload a new sketch. +> :exclamation: Though not recommended, you can override the requirement for a password when enabling OTA for your sketch by including *false* as a parameter to the enabling method as such: `homeSpan.enableOTA(false)`. Use with caution! Anyone who can access the device over your network will now be able to upload a new sketch. -Note that in in order for OTA to properly operate, your sketch must be compiled using by selecting a Parition Scheme under the *Tools* menut that includes OTA partitions. These are usually labeled to indicate if OTA is supported, though sometimes the "default" scheme is also set up for OTA. +Note that in in order for OTA to properly operate, your sketch must be compiled with a partition scheme that includes OTA partitions. Partition schemes are found under the *Tools → Partition Scheme* menu of the Arduino IDE. Select a scheme that indicates it supports OTA. Note that schemes labeled "default" usually include OTA partitions. If unsure, try it out. HomeSpan will let you know if it does or does not. -When OTA is enabled in a sketch, HomeSpan checks that it has been compiled with OTA partitions, and will output a warning to the Arduino Serial Monitor if it does not detect partition scheme that includes OTA partitions, and therefore cannot enable OTA. This checking is done upon start-up of a sketch immediately after WiFi connectivity has been established. +This is because HomeSpan checks that a sketch has been compiled with OTA partitions if OTA has been enabled for that sketch. If OTA has been enabled but HomeSpan does not find any OTA partitioms, it will indicate it cannot start the OTA Server via a warning message sent to the Serial Monitor immediately after WiFi connectivity has been established. Otherwise it will output a confirmation message indicating the OTA Server has sucessfully started. ### OTA Tips and Tricks -The name of the device HomeSpan uses for OTA is the same as the name you assigned in your call to `homeSpan.begin()`. If you have more than one device you intend to maintain with OTA, use `homeSpan.begin()` to give them different names so you can tell them apart when selecting which one to connect to from the Arduino IDE. +* The name of the device HomeSpan uses for OTA is the same as the name you assigned in your call to `homeSpan.begin()`. If you have multiple devices you intend to maintain with OTA, use `homeSpan.begin()` to give them each different names so you can tell them apart when selecting which one to connect to from the Arduino IDE. -Use the `homeSpan.setSketchVersion()` method to set a version number for you sketch. HomeSpan includes this value as part of its HAP MDNS broadcast, which means that by simply inspecting this broadcast you can learn which version of a sketch is running on a remote HomeSpan device, even if you can't plug it into a serial port for use with the Arduino Serial Monitor. In addition to the sketch version, HomeSpan also broadcasts two other useful fields: the version number of the HomeSpan library used when the sketch was compiled, and an indicator of whether OTA is enabled. +* Use the `homeSpan.setSketchVersion()` method to set a version name or number for your sketch. If specified, HomeSpan will include the sketch version name/number as part of its HAP MDNS broadcast. This allows you determine which version of a sketch is running on a remote HomeSpan device, even if you can't plug it into a serial port for use with the Arduino Serial Monitor. In addition to the sketch version name/number, HomeSpan also broadcasts two other useful fields: the version number of the HomeSpan library used when the sketch was compiled, and field indicating whether or not OTA is enabled for the sketch. See [HomeSpan MDNS](MDNS.md) for details on this broadcast and how to browse the data. -The easiest way to inspect HAP MDNS broadcasts is with an MDNS browser. There are a number of free ones available in the App Store. HAP broadcasts will be found under the MDNS service name "_hap._tcp." +* Always test out a new sketch on a local device connected to your computer before uploading it to a remote device via OTA. If the sketch doesn't operate as * expected, you can always upload the previous version, unless the new sketch causes crashes that continously reboot HomeSpan. If HomeSpan can't run the OTA code, you won't be able to upload any sketches via OTA and you'll need to connect the device to a computer for programming via the serial port instead. -Always test out a new sketch on a local device connected to your computer before uploading it to a remote device via OTA. If the sketch doesn't operate as expected, you can always upload the previous version, unless the new sketch causes crashes that continously reboot HomeSpan. If HomeSpan can't run the OTA code, you won't be able to upload any sketches via OTA and you'll need to connect the device to a computer for programming via the serial port instead. - -The ESP32 supports automated rollbacks that are designed to restore a device with a previouslt-working sketch under exactly these circumstances. However, the current Arduino-ESP32 library does not support this feature. +* The ESP32 supports automated rollbacks that are designed to restore a device with a previouslt-working sketch under exactly these circumstances. However, the current Arduino-ESP32 library does not support this feature.