Firmware Upgrade

From ZaberWiki
Jump to navigation Jump to search

Introduction

The Zaber ASCII commands related to firmware upgrade are used for changing the firmware version on a Zaber device with firmware version 6.18 or higher in the field. Zaber Console implements these commands in the Firmware Updater tool, which is the recommended method for updating. There may be instances where implementing this feature in custom software is required though, in which case the below command description will be useful. It's recommended you contact Zaber technical support before implementing these commands.

Device Compatibility with In-the-Field Upgrades
Device Compatibility
X-Series device
Firmware version 7.01 or above 		Compatible
X-Series device
Firmware version 6.18 or above 		Compatible
X-Series device
Firmware version 6.17 or below 		Contact Zaber Technical Support to return stage for firmware upgrade to 6.18+
A-Series device
Firmware version 6.18 or above &
/get system.platform does not return 268500992 		Compatible
A-Series device
Firmware version 6.18 or above &
/get system.platform returns 268500992 		Contact Zaber Technical Support to return stage for hardware replacement
A-Series device
Firmware version 6.17 or below
 Contact Zaber Technical Support to return stage for firmware upgrade to 6.18+ and possible hardware replacement

Upgrade Procedure

A compatible firmware upgrade file (.FWU extension) is required to update a device. Contact Zaber technical support or use the Zaber Console Firmware Updater to get this file. The file will be specific to a serial number.

Note that all integers in a Zaber firmware upgrade file are little endian.

Verifying the Header

The firmware upgrade file should begin with an eight-byte signature which spells out the string ZABERFWU in ASCII. Following this is the revision number of the file format stored as a single byte; this document describes revision 1, so any value other than 1 should be rejected. Following the revision number is a four-byte integer which should be equal to the length of the file, including header.

Generating a Byte Stream

The contents of the firmware upgrade file that follow the header make up instructions using the rule set described below. The instructions will generate a "byte stream", a sequence of bytes which is initially empty and which is incrementally built up as the instructions are executed, that will be sent to the device in the next step. The instructions may instruct you to read a setting from the device, add data to the byte stream, or read or write bits of a interim "register map". This register map can have up to 65,536 register locations (numbered from 0 to 65,535), each of which is initially 0 and can at any time hold either 0 or 1.

These instructions exist to provide checks to ensure a firmware file isn’t accidentally sent to an incompatible device. Firmware files can also contain firmware for more than one device, either of the same type or of different types, which these instructions also allow.

Instructions have varying lengths; in all cases the first byte identifies which instruction is being executed.

Instruction Rules
First Byte Name Total Instruction Length Description
0 AND 7 The remaining six bytes form three two-byte integers, s1, s2, and d. A logical operation is performed between the values stored in registers s1 and s2, and the result is stored into register d. The logical operation is AND if the first byte is 0, OR if the first byte is 1, or XOR if the first byte is 2.
1 OR
2 XOR
3 NOT 5 The remaining four bytes form two two-byte integers, s and d. A logical NOT is performed on the value stored in register s, and the result is stored into register d.
4 IF 4 The second and third bytes form a two-byte integer s, while the fourth byte forms a one-byte integer n. If register s contains the value zero, the next n instructions following this one should be skipped over rather than executed.
5 EMIT Variable The second and third bytes form a two-byte integer n. The following n bytes are appended to the byte stream.
6 ERROR Variable The second byte forms a one-byte integer n. The following n bytes are decoded using UTF-8 to form a text string. The text string is displayed as an error message, no further instructions are executed, and the firmware upgrade operation fails.
7 ISPLATFORM 7 The second through fifth bytes form a four-byte integer p. The sixth and seventh bytes form a two-byte integer d. The command get system.platform is sent to the device to be upgraded. If the value returned by that command is equal to p, then 1 is stored into register d; otherwise, 0 is stored into register d.
8 ISSERIAL 7 The second through fifth bytes form a four-byte integer s. The sixth and seventh bytes form a two-byte integer d. The command get system.serial is sent to the device to be upgraded. If the value returned by that command is equal to s, then 1 is stored into register d; otherwise, 0 is stored into register d.

Transmitting the Data

Once you have successfully executed the instructions and built up a byte stream, you are ready to send the byte stream to the device. Although the upgrade procedure uses the Zaber ASCII protocol, please be aware of the following differences from the normal Zaber communication protocol which apply to some devices during an upgrade:

  • The ASCII protocol must be used. Upgrades cannot be performed using the binary protocol.
  • For firmware 6.xx devices, the RS232 at a baud rate of 115,200 port must be used. Upgrades cannot be performed using the USB or RS485 ports.
  • For firmware 7.xx devices, there are not restrictions on port or baud rate.
  • Daisy-chaining to devices after the device being upgraded is not supported. Any devices after the one being upgraded will not respond to commands until the upgrade is complete.
  • All integers must be provided in decimal during an upgrade; hexadecimal numbers are not supported.
  • A leading plus sign on positive numbers is not permitted.
  • All commands to the device being upgraded must be sent without a message ID.
  • The comm.checksum setting is ignored; all commands to the device being upgraded must be sent without a checksum, and replies will not carry checksums.
  • The backspace key is not supported.
  • Most commands and settings are unavailable.

The overall procedure for sending the byte stream to the device is:

  1. Send the system upgrade start command.
  2. Send a sequence of system upgrade data commands.
  3. Send the system upgrade end command.
  4. Send the system reset command.
  5. Wait for the device to reboot and return to normal operation.

Each of these commands (other than system upgrade end), when successful, includes a number in its reply message. If the number is nonzero, you must take that exact number of bytes from the byte stream, encode those bytes using the URL- and filename-safe variant of base64 to make them safe for transport over the ASCII protocol, and send a system upgrade data command with the resulting text as the parameter. If the number is zero, you must send system upgrade end to finish the installation (for this to happen when there are still some bytes left in the byte stream is an error). If at any point any of the commands is rejected, the upgrade has failed and must be retried from the beginning. In the event of power loss during the upgrade, the device may not be capable of normal operation, but you can restart the upgrade from the beginning.

Example

This example follows a small sample firmware file through the steps described above, ending with sending it to a hypothetical device.

The 191-byte example file is as follows (note that this is not a legitimate firmware file and will not work on a real device): 

00000000  5A 41 42 45 52 46 57 55 01 BF 00 00 00 08 39 30 ZABERFWU......90
00000010  00 00 00 00 03 00 00 00 00 04 00 00 01 06 3B 54 ..............;T
00000020  68 69 73 20 66 69 72 6D 77 61 72 65 20 69 6D 61 his firmware ima
00000030  67 65 20 69 73 20 66 6F 72 20 64 65 76 69 63 65 ge is for device
00000040  20 73 65 72 69 61 6C 20 6E 75 6D 62 65 72 20 31  serial number 1
00000050  32 33 34 35 20 6F 6E 6C 79 2E 07 00 00 02 10 00 2345 only.......
00000060  00 03 00 00 00 00 04 00 00 01 06 33 54 68 69 73 ...........3This
00000070  20 66 69 72 6D 77 61 72 65 20 69 6D 61 67 65 20  firmware image
00000080  69 73 20 66 6F 72 20 70 6C 61 74 66 6F 72 6D 20 is for platform
00000090  32 36 38 35 36 36 35 32 38 20 6F 6E 6C 79 2E 05 268566528 only..
000000A0  04 00 36 D6 22 30 05 16 00 00 00 00 00 FF FF FF ..6."0..........
000000B0  FF 00 00 02 10 00 00 00 00 01 02 03 04 05 06    ...............

Begin by verifying the header. The first eight bytes are 5A 41 42 45 52 46 57 55, which are indeed ZABERFWU in ASCII. The next byte is 01, the correct revision number. The next four bytes are BF 00 00 00, the little-endian encoding of 191, the size of the file.

Next, decode the instructions.

Decoded Instructions
Instruction Number Offset (zero-based) Length Instruction
0 13 7 ISSERIAL, s = 0x00003039 = 12345, d = 0x0000 = 0
1 20 5 NOT, s = 0x0000 = 0, d = 0x0000 = 0
2 25 4 IF, s = 0x0000 = 0, n = 0x01 = 1
3 29 61 ERROR, n = 0x3B = 59, message = “This firmware image is for device serial number 12345 only.”
4 90 7 ISPLATFORM, p = 0x10020000 = 268566528, d = 0x0000 = 0
5 97 5 NOT, s = 0x0000 = 0, d = 0x0000 = 0
6 102 4 IF, s = 0x0000 = 0, n = 0x01 = 1
7 106 53 ERROR, n = 0x33 = 51, message = “This firmware image is for platform 268566528 only.”
8 159 7 EMIT, n = 0x0004 = 4, data = 36 D6 22 30
9 166 25 EMIT, n = 0x0016 = 22, data = 00 00 00 00 FF FF FF FF 00 00 02 10 00 00 00 00 01 02 03 04 05 06

Now execute the instructions:

  1. Begin with an empty byte stream and all registers set to 0.
  2. Execute instruction 0. Send the get system.serial command to the device. It should reply with 12345, in which case set register 0 to 1 (otherwise set register 0 to 0).
  3. Execute instruction 1. Invert the value of register 0. If the serial number had been 12345, then register 0 is now 0, otherwise it is 1.
  4. Execute instruction 2. If register 0 is 0 (i.e. the serial number was 12345), then the next 1 instruction, instruction 3, will be skipped.
  5. Execute instruction 3 only if instruction 2 is not skipping it, i.e. if the serial number is not 12345. Display the error message and stop the process.
  6. Execute instruction 4. Send the get system.platform command to the device. It should reply with 268566528, in which case set register 0 to 1 (otherwise set register 0 to 0).
  7. Execute instruction 5. Invert the value of register 0. If the platform had been 268566528, then register 0 is now 0, otherwise it is 1.
  8. Execute instruction 6. If register 0 is 0 (i.e. the platform was 268566528), then the next 1 instruction, instruction 7, will be skipped.
  9. Execute instruction 7 only if instruction 6 is not skipping it, i.e. if the platform is not 268566528. Display the error message and stop the process.
  10. Execute instruction 8. Add the bytes 36 D6 22 30 to the byte stream.
  11. Execute instruction 9. Add the bytes 00 00 00 00 FF FF FF FF 00 00 02 10 00 00 00 00 01 02 03 04 05 06 to the byte stream.

Assuming the serial number and platform were correct, you have now successfully produced the byte stream 36 D6 22 30 00 00 00 00 FF FF FF FF 00 00 02 10 00 00 00 00 01 02 03 04 05 06.

Finally, send the byte stream to the device:

  1. Send /1 system upgrade start. The device replies with @01 0 OK IDLE NB 20.
  2. The device asked for 20 bytes. Take the first 20 bytes from the byte stream, 36 D6 22 30 00 00 00 00 FF FF FF FF 00 00 02 10 00 00 00 00. Base64url-encode these 20 bytes, producing the 28 characters “NtYiMAAAAAD_____AAACEAAAAAA=”. Note that normal base64 encoding would have produced the slash character (/) in this string, but base64url encoding produces the underscore (_) character instead. Send the command /1 system upgrade data NtYiMAAAAAD_____AAACEAAAAAA=. The device replies with @01 0 OK IDLE NB 6.
  3. The device asked for six bytes. Take the next six bytes from the byte stream, 01 02 03 04 05 06. Base64url-encode these six bytes, producing the eight characters “AQIDBAUG”. Send the command /1 system upgrade data AQIDBAUG. The device replies with @01 0 OK IDLE NB 0.
  4. The device asked for zero bytes, and, cross-checking, there are no more bytes left in the byte stream. Send the command /1 system upgrade end. The device replies with @01 0 OK IDLE NB 0, indicating the byte stream was acceptable and the new firmware is now either installed or staged for installation, depending on the device.
  5. Send the /1 system reset command. The device replies with @01 0 OK IDLE NB 0. Depending on which device you are upgrading, the reset may take more time than usual while the firmware is installed from the staging area. After the reboot is complete, the device is now running the new firmware.
Retrieved from "https://www.zaber.com/w/index.php?title=Firmware_Upgrade&oldid=16890"