SMM firmware installation #65

User story

As a service engineer maintaining SOMANET Safe Motion drives,
I want to install SMM firmware from Motion Master,
so that I can update the safety module without OBLAC Drives.

Context

SMM firmware is installed with four actions of OS command 11 and a restart (#59), after a login for software update (somanet_software sc_drive/module_os_command/src/oscmd_smm_acyclic_handler.xc, sc_certified/module_smm/src/acyclic_communication.c):

1. Action 9 logs in for software update, with the credentials in fs-buffer.
2. Action 10 configures the update. It erases the SMM's flash.
3. Action 11 transmits the binary. On drive firmware 5.2 and newer the command is written first, and then the whole binary is written to fs-buffer in one FoE transfer. The firmware gives this action 600 s.
4. Action 12 finalises the update with the CRC of the binary, 4 bytes little-endian, in fs-buffer.
5. Action 15 restarts the SMM.

oblac runs this sequence in motion-master-req-res-client.ts:5523-5603. The CRC is published with each SMM firmware release, and the user types it. oblac does not compute or check it (oblac-drives src/app/shared/smm-software-update-modal/smm-software-update-modal.component.ts:215-235).

oblac reads a header from the first 500 bytes of the binary: the header version, the SMM firmware version, and the length and checksum of two parts. Header versions below 256 are the first interface version, LW1, and the others LW2 (oblac libs/motion-master-client/src/lib/smm.ts:752-798).

oblac allows an install by encryption (smm.ts:865-957). A version from 1.3 is encrypted, except 1.92 to 1.99 and 99.0. An encrypted binary may only go onto an SMM with encrypted firmware, and an unencrypted one only onto unencrypted firmware. The SMM's current version is read with action 13 on SMM index 0x0001 (#60).

Action 10 erases the flash, and the firmware gives it the general 5 s timeout. The OS command document says the erase takes "a few seconds".

Acceptance criteria

• An smm-firmware-installation procedure takes the binary, username, password and crc. The binary comes from user-cache/smm-firmwares/, or in the request.
• Before it logs in, it parses the header, reads the SMM's current version, and refuses an install that the encryption rule forbids, with a message naming both versions and the rule.
• It refuses a crc that is not 8 hex digits, and a binary shorter than its header.
• It logs out, logs in for software update, configures, transmits, finalises with the given CRC, and restarts the SMM, each with the firmware's timeout. It waits until the drive answers again after the restart.
• A failure after the configure step says that the configure step erased the SMM's flash, and that the install must be run again.
• The procedure logs out on every exit path before the configure step. After the configure step, a cancel is refused, because a stopped transfer leaves the SMM erased.
• The step list separates login, configure, transmit with progress in bytes, finalise and restart.
• Its descriptor sets movesMotor false. Its caveats say that the configure step erases the SMM's flash and that the CRC comes from the release.
• A drive with firmware older than 5.2 is refused, because v6 builds only the 5.2 order of fs-buffer.
• GET /api/smm-firmware/parse takes a binary and returns the parsed header, so the Console can show the version before an install.
• The header parse and the encryption rule are pure functions with unit tests against real LW1 and LW2 binaries.
• The Safety page of SMM parameters and readouts #60 has a Firmware section: pick a binary, see its version against the installed one as upgrade, downgrade or reinstall, type the CRC, log in, and install.
• apps/motion_master/swagger.yml documents the parse route, and the generated client is regenerated.
• Hardware-verified on a Circulo Safe Motion drive: an upgrade, a wrong CRC, a refused install by the encryption rule, and the time action 10 takes. That time is recorded in NEXTGEN.md, and a gap to the 5 s timeout is reported to the firmware team.

Out of scope

• The special versions 77.0, 77.1 and 99.0, and the chain that migrates an SMM from unencrypted to encrypted firmware. They are not needed.
• Computing the CRC. It comes from the release.
• Finding SMM firmware online. Firmware package selection from a list #33 covers drive firmware packages only.

Notes

• This issue depends on SMM OS command 11 and login #59, SMM parameters and readouts #60 and SMM safety status, acknowledge and restart #63.

References

• oblac: libs/motion-master-client/src/lib/smm.ts:752-957, motion-master-req-res-client.ts:5523-5603
• OBLAC Drives: src/app/shared/smm-software-update-modal/
• Firmware: sc_drive/module_os_command/include/os_command/oscmd_smm_acyclic_handler.h:11-13
• SMM OS command 11 and login: SMM OS command 11 and login #59
• SMM parameters and readouts: SMM parameters and readouts #60
• SMM safety status, acknowledge and restart: SMM safety status, acknowledge and restart #63