diff --git a/pages/runbooks.md b/pages/runbooks.md new file mode 100644 index 0000000..2a05e63 --- /dev/null +++ b/pages/runbooks.md @@ -0,0 +1,7 @@ +--- +title: Runbooks +layout: page +has_children: true +--- + +# Runbooks diff --git a/pages/runbooks/update_from_file_on_device.md b/pages/runbooks/update_from_file_on_device.md new file mode 100644 index 0000000..b33a1cb --- /dev/null +++ b/pages/runbooks/update_from_file_on_device.md @@ -0,0 +1,79 @@ +--- +title: Update from file on device +layout: page +parent: Runbooks +--- + +# Update from a file on the device + +From the Nerves application project directory, build the firmware. + +```text +MIX_TARGET= mix firmware +``` + +Connect to the device with SFTP and transfer the firmware bundle (`.fw`) onto +the device. Modify the lines below to match your project. + +```text +sftp +cd /data +lcd _build/_dev/nerves/images/ +lls +put .fw +quit +``` + +Connect to the device's console and run `fwup` from IEx to apply the firmware +update. Reboot once the update is complete. The device will come back up with +the new firmware running. + +```text +cmd "fwup -a -t upgrade -d /dev/ -i /data/.fw" +reboot +``` + +The firmware bundle can be removed from the device if it is no longer needed. + +```text +File.rm "/data/.fw" +``` + +>🛈 Tip +> +>`scp` is an alternative to `sftp`. However, on some systems `scp` responds with +>`lost connection` and fails to transfer the file. The tool used for the file +>transfer is not important as long as the firmware file makes it onto the device. + +## Finding the disk + +The fwup `-d` flag specifies the disk to apply the update to. This is documented +by the `NERVES_FW_DEVPATH` property in your Nerves system fwup config. + +If you need to find the disk without being able to reference the config, run +fwup on the device without the `-d` flag. + +```text +cmd "fwup -a -t upgrade -i /data/.fw" +``` + +This will attempt to auto-detect the disk and will print what it has discovered. +However, the console will hang when doing so. + +```text +Use 7.95 GB memory card found at /dev/mmcblk0? [y/N] +``` + +Break out of the command with Ctrl+C. Copy the path to the disk and paste it +after the `-d` flag in the full fwup command above. + +## Background + +A Nerves device doesn't have to receive a firmware update command remotely. +[fwup](https://github.com/fwup-home/fwup?tab=readme-ov-file#overview) is used to +manage firmware updates, and can be run directly on a Nerves device. This is +actually how the OTA update process works under the hood. + +In this runbook we manually place a firmware file on the device, and then call +`fwup` on the device to perform the firmware update. Once the device is +rebooted, it will come up with the new firmware.