Added bootloader abort events

grodansparadis · Jan 19, 2025 · 56b6107 · 56b6107
1 parent f8d238a
commit 56b6107
Show file tree

Hide file tree

Showing 19 changed files with 145 additions and 28 deletions.
diff --git a/class1.measurement.md b/class1.measurement.md
@@ -454,7 +454,7 @@ This is a measurement of a speed.
 ```
 VSCP_TYPE_MEASUREMENT_ACCELERATION
 ```
-**Default unit:** Metre per second squared (m/s2).
+**Default unit:** Metre per second squared (m/s²).
 
 This is a measurement of acceleration. 
 

diff --git a/class1.measurement32.md b/class1.measurement32.md
@@ -567,7 +567,7 @@ This is a measurement of a speed.
 ```
 VSCP_TYPE_MEASUREMENT_ACCELERATION
 ```
-**Default unit:** Metre per second squared (m/s2).
+**Default unit:** Metre per second squared (m/s²).
 
 This is a measurement of acceleration. 
 

diff --git a/class1.measurement64.md b/class1.measurement64.md
@@ -569,7 +569,7 @@ This is a measurement of a speed.
 ```
 VSCP_TYPE_MEASUREMENT_ACCELERATION
 ```
-**Default unit:** Metre per second squared (m/s2).
+**Default unit:** Metre per second squared (m/s²).
 
 This is a measurement of acceleration. 
 

diff --git a/class1.measurezone.md b/class1.measurezone.md
@@ -561,7 +561,7 @@ This is a measurement of a speed.
 ```
 VSCP_TYPE_MEASUREMENT_ACCELERATION
 ```
-**Default unit:** Metre per second squared (m/s2).
+**Default unit:** Metre per second squared (m/s²).
 
 This is a measurement of acceleration. 
 

diff --git a/class1.protocol.md b/class1.protocol.md
@@ -1226,6 +1226,57 @@ Part of the VSCP boot-loader functionality. This event is a way to check if a de
 **This event was added in version 1.15.0 so we aware that older devices may not support this event.**
 
 
+----
+
+## Type=55 (0x37) - Bootloader abort :id=type55
+```
+VSCP_TYPE_PROTOCOL_BOOT_LOADER_ABORT
+```
+**Not mandatory** Only needed if a VSCP boot loader algorithm is used.
+
+Part of the VSCP boot-loader functionality. This event provide a way to leave the bootloader in a secure fashion if there is problems loading firmware to a device. It is only available if the device has a bootloader that supports this functionality. Typically this is a device that has several firmware slots and can switch between them, and by that switch back to the last known working firmware.
+
+The event can be sent in all states of the bootloading procedure.
+
+[CLASS1.PROTOCOL, Type=56 (Bootloader abort ACK)](./class1.protocol.md#type56) should be sent as a positive response to a bootloader exit or rollback
+
+[CLASS1.PROTOCOL, Type=57 (Bootloader abort NACK)](./class1.protocol.md#type57) should be sent as a negative response to a bootloader exit or rollback
+
+
+**This event was added in version 1.15.10 so we aware that older devices may not support this event.**
+
+
+----
+
+## Type=56 (0x38) - Bootloader abort ACK :id=type56
+```
+VSCP_TYPE_PROTOCOL_BOOT_LOADER_ABORT_ACK
+```
+**Not mandatory** Only needed if a VSCP boot loader algorithm is used.
+
+Part of the VSCP boot-loader functionality. This event is a positive response to a bootloader abort or rollback [CLASS1.PROTOCOL, Type=55 (Bootloader abort)](./class1.protocol.md#type55).
+
+Event is sent before execution of the new firmware starts. It is used to tell the controlling device that the device is ready to leave the bootloader mode and start the new firmware.
+
+**This event was added in version 1.15.10 so we aware that older devices may not support this event.**
+
+
+----
+
+## Type=57 (0x39) - Bootloader abort NACK :id=type57
+```
+VSCP_TYPE_PROTOCOL_BOOT_LOADER_ABORT_NACK
+```
+**Not mandatory** Only needed if a VSCP boot loader algorithm is used.
+
+Part of the VSCP boot-loader functionality. This event is a negative response to a bootloader abort or rollback [CLASS1.PROTOCOL, Type=55 (Bootloader abort)](./class1.protocol.md#type55).
+
+Om a single slot firmware device where a firmware update has failed and there is no working firmware to switch back to this event should be sent to tell the controlling device that we can't leave the bootloader mode until a new full firmware has been loaded.
+
+**This event was added in version 1.15.10 so we aware that older devices may not support this event.**
+
+
+
 ----
 
 [filename](./bottom_copyright.md ':include')
diff --git a/class1.setvaluezone.md b/class1.setvaluezone.md
@@ -564,7 +564,7 @@ This is a measurement of a speed.
 ```
 VSCP_TYPE_MEASUREMENT_ACCELERATION
 ```
-**Default unit:** Metre per second squared (m/s2).
+**Default unit:** Metre per second squared (m/s²).
 
 This is a measurement of acceleration. 
 

diff --git a/class2.level1.measurement.md b/class2.level1.measurement.md
@@ -552,7 +552,7 @@ This is a measurement of a speed.
 ```
 VSCP_TYPE_MEASUREMENT_ACCELERATION
 ```
-**Default unit:** Metre per second squared (m/s2).
+**Default unit:** Metre per second squared (m/s²).
 
 This is a measurement of acceleration. 
 

diff --git a/class2.level1.measurement32.md b/class2.level1.measurement32.md
@@ -553,7 +553,7 @@ This is a measurement of a speed.
 ```
 VSCP_TYPE_MEASUREMENT_ACCELERATION
 ```
-**Default unit:** Metre per second squared (m/s2).
+**Default unit:** Metre per second squared (m/s²).
 
 This is a measurement of acceleration. 
 

diff --git a/class2.level1.measurement64.md b/class2.level1.measurement64.md
@@ -553,7 +553,7 @@ This is a measurement of a speed.
 ```
 VSCP_TYPE_MEASUREMENT_ACCELERATION
 ```
-**Default unit:** Metre per second squared (m/s2).
+**Default unit:** Metre per second squared (m/s²).
 
 This is a measurement of acceleration. 
 

diff --git a/class2.level1.measurezone.md b/class2.level1.measurezone.md
@@ -553,7 +553,7 @@ This is a measurement of a speed.
 ```
 VSCP_TYPE_MEASUREMENT_ACCELERATION
 ```
-**Default unit:** Metre per second squared (m/s2).
+**Default unit:** Metre per second squared (m/s²).
 
 This is a measurement of acceleration. 
 

diff --git a/class2.level1.protocol.md b/class2.level1.protocol.md
@@ -1476,6 +1476,69 @@ Part of the VSCP boot-loader functionality. This event is a way to check if a de
 
 
 
+----
+
+
+## Type=55 (0x37) - Bootloader abort :id=type55
+
+```
+VSCP_TYPE_PROTOCOL_BOOT_LOADER_ABORT
+```
+**Not mandatory** Only needed if a VSCP boot loader algorithm is used.
+
+Part of the VSCP boot-loader functionality. This event provide a way to leave the bootloader in a secure fashion if there is problems loading firmware to a device. It is only available if the device has a bootloader that supports this functionality. Typically this is a device that has several firmware slots and can switch between them, and by that switch back to the last known working firmware.
+
+The event can be sent in all states of the bootloading procedure.
+
+[CLASS1.PROTOCOL, Type=56 (Bootloader abort ACK)](./class1.protocol.md#type56) should be sent as a positive response to a bootloader exit or rollback
+
+[CLASS1.PROTOCOL, Type=57 (Bootloader abort NACK)](./class1.protocol.md#type57) should be sent as a negative response to a bootloader exit or rollback
+
+
+**This event was added in version 1.15.10 so we aware that older devices may not support this event.**
+
+
+
+
+----
+
+
+## Type=56 (0x38) - Bootloader abort ACK :id=type56
+
+```
+VSCP_TYPE_PROTOCOL_BOOT_LOADER_ABORT_ACK
+```
+**Not mandatory** Only needed if a VSCP boot loader algorithm is used.
+
+Part of the VSCP boot-loader functionality. This event is a positive response to a bootloader abort or rollback [CLASS1.PROTOCOL, Type=55 (Bootloader abort)](./class1.protocol.md#type55).
+
+Event is sent before execution of the new firmware starts. It is used to tell the controlling device that the device is ready to leave the bootloader mode and start the new firmware.
+
+**This event was added in version 1.15.10 so we aware that older devices may not support this event.**
+
+
+
+
+----
+
+
+## Type=57 (0x39) - Bootloader abort NACK :id=type57
+
+```
+VSCP_TYPE_PROTOCOL_BOOT_LOADER_ABORT_NACK
+```
+**Not mandatory** Only needed if a VSCP boot loader algorithm is used.
+
+Part of the VSCP boot-loader functionality. This event is a negative response to a bootloader abort or rollback [CLASS1.PROTOCOL, Type=55 (Bootloader abort)](./class1.protocol.md#type55).
+
+Om a single slot firmware device where a firmware update has failed and there is no working firmware to switch back to this event should be sent to tell the controlling device that we can't leave the bootloader mode until a new full firmware has been loaded.
+
+**This event was added in version 1.15.10 so we aware that older devices may not support this event.**
+
+
+
+
+
 ----
 
 

diff --git a/class2.level1.setvaluezone.md b/class2.level1.setvaluezone.md
@@ -553,7 +553,7 @@ This is a measurement of a speed.
 ```
 VSCP_TYPE_MEASUREMENT_ACCELERATION
 ```
-**Default unit:** Metre per second squared (m/s2).
+**Default unit:** Metre per second squared (m/s²).
 
 This is a measurement of acceleration. 
 

diff --git a/class2.measurement_float.md b/class2.measurement_float.md
@@ -568,7 +568,7 @@ This is a measurement of a speed.
 ```
 VSCP_TYPE_MEASUREMENT_ACCELERATION
 ```
-**Default unit:** Metre per second squared (m/s2).
+**Default unit:** Metre per second squared (m/s²).
 
 This is a measurement of acceleration. 
 

diff --git a/class2.measurement_str.md b/class2.measurement_str.md
@@ -569,7 +569,7 @@ This is a measurement of a speed.
 ```
 VSCP_TYPE_MEASUREMENT_ACCELERATION
 ```
-**Default unit:** Metre per second squared (m/s2).
+**Default unit:** Metre per second squared (m/s²).
 
 This is a measurement of acceleration. 
 

diff --git a/images/vscp_std_bootloader_algorithm.png b/images/vscp_std_bootloader_algorithm.png
diff --git a/images/vscp_std_bootloader_algorithm_detail.png b/images/vscp_std_bootloader_algorithm_detail.png
diff --git a/variables.xml b/variables.xml
@@ -1,4 +1,4 @@
 <var>
-    <creation-time>2025-01-13 11:26:00</creation-time>
-    <document-version>1.15.9</document-version>
+    <creation-time>2025-01-19 17:31:00</creation-time>
+    <document-version>1.15.10</document-version>
 </var>
diff --git a/vscp_boot_loader_algorithm.md b/vscp_boot_loader_algorithm.md
@@ -20,22 +20,24 @@ Most flash devices are programmed block by block. The boot loader algorithm must
 
 The boot loader sequence is as follows:
 
-*  **master** - device that initiate boot loading process and uploads firmware
-*  **node** - Device that will get it's firmware updated.
- 1.  The master instructs the node to enter boot loader mode by sending an [enter boot loader mode](./class1.protocol.md#type12) event to the node. This event have information on which boot loader method that is expected by the master. This can be the VSCP boot loader which is described here or another boot loader. __If this event is received in an stage below the boot loading process should be restarted.__
- 2.  The node confirms that it is ready for code loading with the requested boot loader algorithm by sending the [ACK boot loader mode](./class1.protocol.md#type13) event. Block size and number of blocks are sent as arguments in the acknowledge event. The node respond with [NACK boot loader mode event](./class1.protocol.md#type14) if it can't handle the requested boot loader algorithm or because of some other reason cant initiate the boot loading process.
- 3.  The master sends a [start block data transfer](./class1.protocol.md#type15) event to specify which block should be programmed and by that initiating the transfer of data for the block. 
- 4.  The node confirms block transfer by sending an [ACK data block](./class1.protocol.md#type17) event. 
- 5.  The master sends one or several [block data](./class1.protocol.md#type16) events until the complete block is transferred. 
- 6.  When all data for a block is received by a node it sends a [block ACK](./class1.protocol.md#type17) event to acknowledge the reception of a complete block. 
- 7.  The master now sends a program block event to the node to make it write the block buffer into flash memory. 
- 8.  The node confirms the block programming by responding with an [ACK program block](./class1.protocol.md#type20) event.
- 9.  The next block is handled or the node is taken out of the boot loader mode by sending a [drop nickname/reset device](./class1.protocol.md#type8) event. 
- 10.  To activate the new program code the master sends an [activate new image](./class1.protocol.md#type22) event with the 16 bit CRC for the full new firmware as an argument. The new node should come up after reboot. The 16-bit CCITT CRC is used. [One activate new image ACK](./class1.protocol.md#type48) event is set if this happens if something is wrong an [activate new image NACK](./class1.protocol.md#type48) event is sent.
+*  **controller** - device that initiate boot loading process and uploads firmware
+*  **device** - Device that will get it's firmware updated.
+ 1.  The controller instructs the device to enter boot loader mode by sending an [enter boot loader mode](./class1.protocol.md#type12) event to the device. This event have information on which boot loader method that is expected by the controller. This can be the VSCP boot loader which is described here or another boot loader. __If this event is received in an stage below the boot loading process should be restarted.__
+ 2.  The device confirms that it is ready for code loading with the requested boot loader algorithm by sending the [ACK boot loader mode](./class1.protocol.md#type13) event. Block size and number of blocks are sent as arguments in the acknowledge event. The device respond with [NACK boot loader mode event](./class1.protocol.md#type14) if it can't handle the requested boot loader algorithm or because of some other reason cant initiate the boot loading process.
+ 3.  The controller sends a [start block data transfer](./class1.protocol.md#type15) event to specify which block should be programmed and by that initiating the transfer of data for the block. 
+ 4.  The device confirms block transfer by sending an [ACK data block](./class1.protocol.md#type17) event. 
+ 5.  The controller sends one or several [block data](./class1.protocol.md#type16) events until the complete block is transferred. 
+ 6.  When all data for a block is received by a device it sends a [block ACK](./class1.protocol.md#type17) event to acknowledge the reception of a complete block. 
+ 7.  The controller now sends a program block event to the device to make it write the block buffer into flash memory. 
+ 8.  The device confirms the block programming by responding with an [ACK program block](./class1.protocol.md#type20) event.
+ 9.  The next block is handled or the device is taken out of the boot loader mode by sending a [drop nickname/reset device](./class1.protocol.md#type8) event. 
+ 10.  To activate the new program code the controller sends an [activate new image](./class1.protocol.md#type22) event with the 16 bit CRC for the full new firmware as an argument. The new device should come up after reboot. The 16-bit CCITT CRC is used. [One activate new image ACK](./class1.protocol.md#type48) event is set if this happens if something is wrong an [activate new image NACK](./class1.protocol.md#type48) event is sent.
 
 The boot-loader is built to direct control flash if other methods such as intermediate storage is used. Data can be loaded direct and program block can just get a dummy ACK. 
 
-![Firmware update procedure](./images/vscp_std_boot_loader_algorithm.png)
+The controller can always abort the bootloader process by sending a [bootloader abort](./class1.protocol.md#type55) event. If the device accept it or not depends if the device can switch to a working firmware or not. Doing this usualy requires the device to have a dual (or more) firmware setup.
+
+![Firmware update procedure](./images/vscp_std_bootloader_algorithm.png)
 Diagram by **Andreas Merkle**
 
 #### Type of memory to write (byte 4)
@@ -44,7 +46,7 @@ This is the currently defined  memory types that can be used.
 
  | Memory type | Description | 
  | :-----------: | ----------- | 
- | 0 or byte absent | PROGRAM Flash (status quo for old nodes) | 
+ | 0 or byte absent | PROGRAM Flash (status quo for old devices) | 
  | 1 | DATA (EEPROM, MRAM, FRAM) | 
  | 2 | CONFIG (CPU configuration) | 
  | 3 | RAM | 

diff --git a/vscp_specification_history.md b/vscp_specification_history.md
@@ -2,6 +2,7 @@
 
  | Date       | By   | Description |
  | ---------- | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+|2025-01-19| AKHE | Added bootloader abort events |
 |2025-01-13| AKHE | Misc updates/fixed for measurement units. [See](https://github.com/grodansparadis/vscp/discussions/279#discussioncomment-11796872) |
 |2025-01-09| AKHE | CLASS1.MEASUREMENT, type13/14 new units. Fixed faulty link. Fixed unit error. |
 |2025-01-07| AKHE | Added events CLASS1_CONTROL: VSCP_TYPE_CONTROL_TURN_ALL_OFF (17), VSCP_TYPE_CONTROL_TURN_ALL_ON (18) VSCP_TYPE_CONTROL_TURN_ALL_X (19) Fixes grodansparadis/vscp#278 |