|
| 1 | +# Firmware Updates (FOTA) |
| 2 | + |
| 3 | +This guide covers how to perform Firmware Over The Air (FOTA) updates using nRF Cloud, including both the web UI and REST API methods. |
| 4 | + |
| 5 | +## Firmware Versioning |
| 6 | + |
| 7 | +### Version Components |
| 8 | + |
| 9 | +Firmware versions are defined in `app/VERSION`: |
| 10 | + |
| 11 | +- **VERSION_MAJOR**: Major version |
| 12 | +- **VERSION_MINOR**: Minor version |
| 13 | +- **PATCHLEVEL**: Patch level |
| 14 | +- **VERSION_TWEAK**: Additional component (typically 0) |
| 15 | +- **EXTRAVERSION**: Extra string (e.g., "dev", "rc1") |
| 16 | + |
| 17 | +Example resulting in version `1.2.3-dev`: |
| 18 | + |
| 19 | +```plaintext |
| 20 | +VERSION_MAJOR = 1 |
| 21 | +VERSION_MINOR = 2 |
| 22 | +PATCHLEVEL = 3 |
| 23 | +VERSION_TWEAK = 0 |
| 24 | +EXTRAVERSION = dev |
| 25 | +``` |
| 26 | + |
| 27 | +### Preparing Firmware |
| 28 | + |
| 29 | +1. **Update `app/VERSION`** - Increment the appropriate version component |
| 30 | +2. **Build the firmware** |
| 31 | + |
| 32 | + Using the command line: |
| 33 | + |
| 34 | + ```bash |
| 35 | + west build -p -b thingy91x/nrf9151/ns # Make sure you build for the appropriate board |
| 36 | + ``` |
| 37 | + |
| 38 | + Or use the nRF Connect for VS Code extension - see the [Getting Started](getting_started.md) guide for details on building with the extension. |
| 39 | + |
| 40 | +3. **Locate update bundles**: |
| 41 | + - `build/app/zephyr/dfu_application.zip` - Application firmware update |
| 42 | + - `build/app/zephyr/dfu_mcuboot.zip` - Bootloader update |
| 43 | + |
| 44 | +### Version Verification |
| 45 | + |
| 46 | +**Important**: The `fwversion` field in a firmware bundle is independent from the device's reported version. |
| 47 | + |
| 48 | +To verify a successful update: |
| 49 | + |
| 50 | +- **Application updates**: Check that the FOTA job shows **Completed** status AND the **App Version** field in device information reflects the new version |
| 51 | +- **Modem updates**: Check that the FOTA job shows **Completed** status AND the **Modem Firmware** field in device information shows the new version |
| 52 | + |
| 53 | + |
| 54 | + |
| 55 | +## Performing FOTA Updates |
| 56 | + |
| 57 | +### Option 1: nRF Cloud Web UI |
| 58 | + |
| 59 | +This is the recommended method for manual updates and testing. |
| 60 | + |
| 61 | +1. **Navigate to Firmware Updates** in the nRF Cloud portal under **Device Management** |
| 62 | +2. **Create Update Bundle**: |
| 63 | + - Click "Add bundle" |
| 64 | + - Upload your bundle file: |
| 65 | + - For application updates: `dfu_application.zip` |
| 66 | + - For bootloader updates: `dfu_mcuboot.zip` |
| 67 | + - Set **Update Type** (e.g., LTE) |
| 68 | + - Enter a **Name** for the bundle |
| 69 | + - Enter a **Version** string (can be any identifier - this is the `fwversion` shown in the bundle list) |
| 70 | + - Click "Create/Upload Bundle" |
| 71 | + |
| 72 | +  |
| 73 | + |
| 74 | +3. **Create FOTA Update**: |
| 75 | + - Enter a **Name** and a **Description** of the update |
| 76 | + - Select target device(s) via device or group selection |
| 77 | + - Click on **Deploy now** |
| 78 | + - Click "Create FOTA Update" |
| 79 | + |
| 80 | +4. **Monitor Progress**: |
| 81 | + - View job status in the "Overall Progress" section of the update |
| 82 | + - Status will progress: Queued → In Progress → Downloading → Completed |
| 83 | + - The device will automatically download and apply the update once it becomes online |
| 84 | + |
| 85 | +5. **Verify Update**: |
| 86 | + - Navigate to your device page, **Device Management** → **Devices** and select your device |
| 87 | + - Click on **Device info** under the **Device Information** card |
| 88 | + - Check the **App Version** (for app updates) or **Modem Firmware** (for modem updates) field |
| 89 | + - Confirm the version matches your new firmware |
| 90 | + |
| 91 | +For detailed UI instructions, see [nRF Cloud FOTA Tutorial](https://docs.nordicsemi.com/bundle/nrf-cloud/page/Devices/FirmwareUpdate/FOTATutorial.html). |
| 92 | + |
| 93 | +### Option 2: REST API |
| 94 | + |
| 95 | +For automated workflows and CI/CD integration, use the REST API. |
| 96 | + |
| 97 | +#### Setup |
| 98 | + |
| 99 | +```bash |
| 100 | +export API_KEY="your-nrf-cloud-api-key" |
| 101 | +export DEVICE_ID="your-device-id" |
| 102 | +``` |
| 103 | + |
| 104 | +Find your API key in **User Account** settings in nRF Cloud. See [nRF Cloud REST API](https://api.nrfcloud.com/) for reference. |
| 105 | + |
| 106 | +#### Complete Update Workflow |
| 107 | + |
| 108 | +1. **Create manifest and upload bundle**: |
| 109 | + |
| 110 | + ```bash |
| 111 | + export BIN_FILE="build/app/zephyr/dfu_application.zip" |
| 112 | + export FW_VERSION="1.2.3" |
| 113 | + |
| 114 | + # Upload bundle to nRF Cloud |
| 115 | + curl -X POST "https://api.nrfcloud.com/v1/firmwares" \ |
| 116 | + -H "Authorization: Bearer ${API_KEY}" \ |
| 117 | + -H "Content-Type: application/zip" \ |
| 118 | + --data-binary @${BIN_FILE} |
| 119 | + |
| 120 | + # Extract bundle ID from response URI |
| 121 | + export BUNDLE_ID="<bundle-id-from-response>" |
| 122 | + ``` |
| 123 | + |
| 124 | +2. **Create and apply FOTA job**: |
| 125 | + |
| 126 | + ```bash |
| 127 | + # Create job |
| 128 | + JOB_RESPONSE=$(curl -X POST "https://api.nrfcloud.com/v1/fota-jobs" \ |
| 129 | + -H "Authorization: Bearer ${API_KEY}" \ |
| 130 | + -H "Content-Type: application/json" \ |
| 131 | + -d "{\"deviceIds\": [\"${DEVICE_ID}\"], \"bundleId\": \"${BUNDLE_ID}\"}") |
| 132 | + |
| 133 | + export JOB_ID=$(echo $JOB_RESPONSE | jq -r '.jobId') |
| 134 | + |
| 135 | + # Apply job |
| 136 | + curl -X POST "https://api.nrfcloud.com/v1/fota-jobs/${JOB_ID}/apply" \ |
| 137 | + -H "Authorization: Bearer ${API_KEY}" |
| 138 | + ``` |
| 139 | + |
| 140 | +3. **Monitor job status**: |
| 141 | + |
| 142 | + ```bash |
| 143 | + curl -X GET "https://api.nrfcloud.com/v1/fota-jobs/${JOB_ID}" \ |
| 144 | + -H "Authorization: Bearer ${API_KEY}" \ |
| 145 | + -H "Accept: application/json" |
| 146 | + ``` |
| 147 | + |
| 148 | + Job status values: `QUEUED`, `IN_PROGRESS`, `DOWNLOADING`, `SUCCEEDED`, `FAILED`, `TIMED_OUT`, `CANCELLED`, `REJECTED` |
| 149 | + |
| 150 | +4. **Verify the update** by checking the device information in nRF Cloud (App Version or Modem Firmware field) |
| 151 | + |
| 152 | +#### API Reference |
| 153 | + |
| 154 | +**List FOTA jobs**: |
| 155 | + |
| 156 | +```bash |
| 157 | +curl -X GET "https://api.nrfcloud.com/v1/fota-jobs" \ |
| 158 | + -H "Authorization: Bearer ${API_KEY}" |
| 159 | +``` |
| 160 | + |
| 161 | +**Cancel FOTA job**: |
| 162 | + |
| 163 | +```bash |
| 164 | +curl -X PUT "https://api.nrfcloud.com/v1/fota-jobs/${JOB_ID}/cancel" \ |
| 165 | + -H "Authorization: Bearer ${API_KEY}" |
| 166 | +``` |
| 167 | + |
| 168 | +**Delete FOTA job**: |
| 169 | + |
| 170 | +```bash |
| 171 | +curl -X DELETE "https://api.nrfcloud.com/v1/fota-jobs/${JOB_ID}" \ |
| 172 | + -H "Authorization: Bearer ${API_KEY}" |
| 173 | +``` |
| 174 | + |
| 175 | +**Delete firmware bundle**: |
| 176 | + |
| 177 | +```bash |
| 178 | +curl -X DELETE "https://api.nrfcloud.com/v1/firmwares/${BUNDLE_ID}" \ |
| 179 | + -H "Authorization: Bearer ${API_KEY}" |
| 180 | +``` |
| 181 | + |
| 182 | +## Troubleshooting |
| 183 | + |
| 184 | +- **Update not applying**: Ensure the device is connected to nRF Cloud and actively polling for updates |
| 185 | +- **Version not updating**: The device must successfully complete the update and report back to nRF Cloud. Check FOTA job status is "Completed" |
| 186 | +- **Wrong firmware type**: Ensure you're using the correct bundle (`dfu_application.zip` for app, `dfu_mcuboot.zip` for bootloader) |
| 187 | + |
0 commit comments