|
| 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 | +3. **Create FOTA Update**: |
| 73 | + - Enter a **Name** and a **Description** of the update |
| 74 | + - Select target device(s) via device or group selection |
| 75 | + - Click on **Deploy now** |
| 76 | + - Click "Create FOTA Update" |
| 77 | + |
| 78 | +4. **Monitor Progress**: |
| 79 | + - View job status in the "Overall Progress" section of the update |
| 80 | + - Status will progress: Queued → In Progress → Downloading → Completed |
| 81 | + - The device will automatically download and apply the update once it becomes online |
| 82 | + |
| 83 | +5. **Verify Update**: |
| 84 | + - Navigate to your device page, **Device Management** → **Devices** and select your device |
| 85 | + - Click on **Device info** under the **Device Information** card |
| 86 | + - Check the **App Version** (for app updates) or **Modem Firmware** (for modem updates) field |
| 87 | + - Confirm the version matches your new firmware |
| 88 | + |
| 89 | +### Option 2: REST API |
| 90 | + |
| 91 | +For automated workflows and CI/CD integration, use the REST API. |
| 92 | + |
| 93 | +#### Setup |
| 94 | + |
| 95 | +```bash |
| 96 | +export API_KEY=<your-nrf-cloud-api-key> |
| 97 | +export DEVICE_ID=<your-device-id> |
| 98 | +``` |
| 99 | + |
| 100 | +Find your API key in **User Account** settings in nRF Cloud. See [nRF Cloud REST API](https://api.nrfcloud.com/) for reference. |
| 101 | + |
| 102 | +#### Complete Update Workflow |
| 103 | + |
| 104 | +1. **Create manifest and upload bundle**: |
| 105 | + |
| 106 | + ```bash |
| 107 | + # Set path to your application binary |
| 108 | + export BIN_FILE="build/app/zephyr/zephyr.signed.bin" |
| 109 | + export FW_VERSION="1.2.3" |
| 110 | + |
| 111 | + # Create manifest.json with firmware details |
| 112 | + cat > manifest.json << EOF |
| 113 | + { |
| 114 | + "name": "My Firmware", |
| 115 | + "description": "Firmware description", |
| 116 | + "fwversion": "${FW_VERSION}", |
| 117 | + "format-version": 1, |
| 118 | + "files": [ |
| 119 | + { |
| 120 | + "file": "$(basename ${BIN_FILE})", |
| 121 | + "type": "application", |
| 122 | + "size": $(stat -f%z ${BIN_FILE}) |
| 123 | + } |
| 124 | + ] |
| 125 | + } |
| 126 | + EOF |
| 127 | +
|
| 128 | + # Create zip containing firmware and manifest |
| 129 | + zip -j firmware.zip ${BIN_FILE} manifest.json |
| 130 | +
|
| 131 | + # Upload to nRF Cloud and extract bundle ID |
| 132 | + UPLOAD_RESPONSE=$(curl -X POST "https://api.nrfcloud.com/v1/firmwares" \ |
| 133 | + -H "Authorization: Bearer ${API_KEY}" \ |
| 134 | + -H "Content-Type: application/zip" \ |
| 135 | + --data-binary @firmware.zip) |
| 136 | +
|
| 137 | + # Extract the bundle ID from the response (UUID from the URI path) |
| 138 | + export BUNDLE_ID=$(echo $UPLOAD_RESPONSE | jq -r '.uris[0]' | grep -oE '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}') |
| 139 | + ``` |
| 140 | +
|
| 141 | +2. **Create and apply FOTA job**: |
| 142 | +
|
| 143 | + ```bash |
| 144 | + # Create job |
| 145 | + JOB_RESPONSE=$(curl -X POST "https://api.nrfcloud.com/v1/fota-jobs" \ |
| 146 | + -H "Authorization: Bearer ${API_KEY}" \ |
| 147 | + -H "Content-Type: application/json" \ |
| 148 | + -d "{\"deviceIds\": [\"${DEVICE_ID}\"], \"bundleId\": \"${BUNDLE_ID}\"}") |
| 149 | +
|
| 150 | + export JOB_ID=$(echo $JOB_RESPONSE | jq -r '.jobId') |
| 151 | +
|
| 152 | + # Apply job |
| 153 | + curl -X POST "https://api.nrfcloud.com/v1/fota-jobs/${JOB_ID}/apply" \ |
| 154 | + -H "Authorization: Bearer ${API_KEY}" |
| 155 | + ``` |
| 156 | +
|
| 157 | +3. **Monitor job status**: |
| 158 | +
|
| 159 | + ```bash |
| 160 | + curl -X GET "https://api.nrfcloud.com/v1/fota-jobs/${JOB_ID}" \ |
| 161 | + -H "Authorization: Bearer ${API_KEY}" \ |
| 162 | + -H "Accept: application/json" |
| 163 | + ``` |
| 164 | +
|
| 165 | + Job status values: `QUEUED`, `IN_PROGRESS`, `DOWNLOADING`, `SUCCEEDED`, `FAILED`, `TIMED_OUT`, `CANCELLED`, `REJECTED` |
| 166 | +
|
| 167 | +4. **Verify the update** by checking the device information in nRF Cloud (App Version or Modem Firmware field) |
| 168 | +
|
| 169 | +#### API Reference |
| 170 | +
|
| 171 | +**List FOTA jobs**: |
| 172 | +
|
| 173 | +```bash |
| 174 | +curl -X GET "https://api.nrfcloud.com/v1/fota-jobs" \ |
| 175 | + -H "Authorization: Bearer ${API_KEY}" |
| 176 | +``` |
| 177 | +
|
| 178 | +**Cancel FOTA job**: |
| 179 | +
|
| 180 | +```bash |
| 181 | +curl -X PUT "https://api.nrfcloud.com/v1/fota-jobs/${JOB_ID}/cancel" \ |
| 182 | + -H "Authorization: Bearer ${API_KEY}" |
| 183 | +``` |
| 184 | +
|
| 185 | +**Delete FOTA job**: |
| 186 | +
|
| 187 | +```bash |
| 188 | +curl -X DELETE "https://api.nrfcloud.com/v1/fota-jobs/${JOB_ID}" \ |
| 189 | + -H "Authorization: Bearer ${API_KEY}" |
| 190 | +``` |
| 191 | +
|
| 192 | +**Delete firmware bundle**: |
| 193 | +
|
| 194 | +```bash |
| 195 | +curl -X DELETE "https://api.nrfcloud.com/v1/firmwares/${BUNDLE_ID}" \ |
| 196 | + -H "Authorization: Bearer ${API_KEY}" |
| 197 | +``` |
0 commit comments