7. Software update and recovery

This section covers how to restore firmware settings, update the firmware components, perform factory reset and update the operating system.

7.1 Restore firmware settings

CCSettingsConsole can be used to reset the firmware settings to the factory default settings, if needed. Use the following command:

$ sudo ccsettingsconsole --advanced --factory

7.2 Updating firmware components

The Advanced category of CCSettingsConsole is also used to load new firmware into the device for the System Supervisor (SS), Display MCU (DMCU), and I/O MCU.

It is also possible to verify whether a given firmware file matches the currently installed version. By using the –verify option, the system compares the file against the existing firmware and reports any mismatches. Note: No firmware is written to the device during the verification process.

After each program or verify action, the device must be shut down. Press the shutdown button or other alternatives to shut down the OS after a firmware update.

The recommended way to perform firmware updates is via the CCSettingsConsole application. Alternatively, you can use CCAux API functions directly from your own program.

Warning

Errors during an update of firmware components can set the module in an unrecoverable state. In such case, the module must be shipped to factory for repair, or have internal parts replaced through service interfaces. Make sure that you carefully choose the correct files for updating and follow the instructions from the tools, including powering off the device when prompted.

Starting with CC Linux 4.2, every firmware file should be accompanied by a corresponding description file in .json format. This JSON file contains metadata that allows ccsettingsconsole to verify whether the firmware is compatible with the target microcontroller.

The JSON file must have the same name as the firmware file, but with a .json extension instead of .hex or .bin. For example, if the firmware file is named device_firmware.hex, the description file should be named device_firmware.json.

The firmware and its JSON description file can also be bundled together in a single .zip archive. If a ZIP file is provided, ccsettingsconsole will automatically extract its contents and proceed with verification. The ZIP file will be extracted in the folder where it is located, so you must ensure that you have write permission to this folder.

Validation can be bypassed by using the –force or –no-compat-check options. Use these options with caution, as disabling compatibility checks may lead to the firmware being installed on an unsupported microcontroller, which could result in malfunction or system instability.

To update the firmware, copy the firmware file to a USB stick and connect it to the device. Login and issue corresponding commands for each firmware as described in the following sections.

7.2.1 System Supervisor (SS) firmware

$ sudo ccsettingsconsole --advanced --update=SS --filepath=<full-path-to-file>

If only verification is required, use the following command instead:

$ sudo ccsettingsconsole --advanced --verify=SS --filepath=<full-path-to-file>

7.2.2 Display MCU firmware

Login and issue the following command to update the Display MCU:

$ sudo ccsettingsconsole --advanced --update=Display --filepath=<full-path-to-file>

If only verification is required, use the following command instead:

$ sudo ccsettingsconsole --advanced --verify=Display --filepath=<full-path-to-file>
Table 1: Display MCU availability.

X1200

V700

V1x00

Vx10

Yukon

No

No

Yes

Yes

Yes

7.2.3 I/O MCU firmware

Login and issue the following command to update the I/O MCU:

$ sudo ccsettingsconsole --advanced --update=Iomcu --filepath=<full-path-to-file>

If only verification is required, use the following command instead:

$ sudo ccsettingsconsole --advanced --verify=Iomcu --filepath=<full-path-to-file>
Table 1: I/O MCU availability.

X1200

V700

V1x00

Vx10

Yukon

No

No

No

Yes

Yes

7.3 Factory reset of operating system

As explained in the introduction, the user data or configuration files are stored on the /etc read-only folder of root filesystem, which is overlayed to /data/cc-etc of read-write filesystem. It is possible to remove all the settings and files under that location, and have the device generate the default contents back upon a restart of the device after the factory reset.

The factoy reset is done via the command

$ sudo ccsettingsconsole --advanced --factory_reset

Note

The user has to manually reboot the device after the above command is executed.

After the reboot of the device, the default user settings and files will be restored.

7.4 Updating the operating system

The CC Linux system on the device can be updated by a robust software update mechanism called RAUC, which is a major feature on the CC Linux 4 as explained in the introduction. Please refer CCLinux-RaucGuide [2] to have more insights above RAUC software update mechanism, how the RAUC update works and how to update the software using RAUC.

Consider the device is booted up with root filesystem A, and RAUC will check the inactive root filesystem (which in this example is root filesystem B) and the update will be performed on the inactive root filesystem. On system reboot, after a successful update, the device will boot up with root filesystem B where the update image is installed.

Warning

Errors during an update can set the module in an unrecoverable state. In such case, the module must then be shipped to our factory for repair, or have internal parts replaced through service partners.

The complete system consists of six partitions in the eMMC/CFast:

CC Linux 4
+-------------------+
|       Boot        |  -->  bootloader
+-------------------+
|     RootFs A      |  -->  kernel + root filesystem A
+-------------------+
|     RootFs B      |  -->  kernel + root filesystem B
+-------------------+
|      AppFs A      |  -->  applications filesystem A
+-------------------+
|      AppFs B      |  -->  applications filesystem B
+-------------------+
|       Data        |  -->  user data filesystem
+-------------------+

All the partitions except the data partition can be updated. Normally, software updates are for the kernel, root filesystem and application filesystem, though they may occasionally concern the other partitions, for example the bootloader.

The software update can be done as a combination of partitions:

  1. OS update (bootloader + Root filesystem(with Kernel))

  2. System update (bootloader + Root filesystem(with Kernel) + application filesystem)

or individual partitions:

  1. Bootloader update

  2. Root Filesystem (with Kernel) update

  3. Application Filesystem update

Note

If only the application filesystem has to be updated, it is recommended to do a System update.

New versions of the operating system are released as Rauc bundles with extension .raucb. File names will differ depending on which parts are being updated. Additionally, file names will vary depending on the device model.

In the following sections, an example CCpilot V700 device model is used to illustrate the process.

Warning

For updating the operating system to CC Linux 4 from the the previous versions of CC Linux, the only way to update the system is by using UUU approach described in CCLinux–SystemUpdateUsingUuu (not available for X1200).

7.4.1 Automatic update of the operating system

This section shows how the software update is done automatically via USB. For the automatic update, the Crosscontrol binary cc-update shipped with the CC Linux 4 operating system will be used.

  1. When the update image (CCpilot-V700-x.x.x.x-os-update-bundle.raucb) is ready, copy the update image to the root folder of the USB memory.

Warning

Make sure not to have more than one update rauc bundle in the root folder of the USB memory

  1. Insert to USB to the device after the update bundle is copied to the USB.

  2. The USB will be automounted on the CC Linux operating system.

  3. The update of the operating system using cc-update binary will begin soon after the automounting of USB, without requiring any user interaction to complete. The start of the update can be confirmed by the short beep and the led will start blinking Yellow until the update is finished.

  4. On successful update of the device, the led will be turned Green and a long beep for 2 seconds will be heared. If the update is unsuccessful, then the led will blink Red with audible falling tone beeps and then turned Green for the system to be updated again.

  5. After successful update, the device will be rebooted automatically by the cc-update binary.

Note

Make sure to remove the USB from the device soon after the system is updated.

  1. Verify the system is booted up with the updated image after the reboot.

7.4.2 Manual update of the operating system

This update method requires the device is booted into either root filesystem A or B and you are logged in to device with the ccs user.

  1. When the OS update image bundle (CCpilot-V700-x.x.x.x-os-update-bundle.raucb) is ready, copy the update image from the host system to the read-write data partition of the device, using scp:

$ scp CCpilot-V700-x.x.x.x-os-update-bundle.raucb ccs@xxxx:

Warning

Make sure you have enough space in the user data partition to copy the OS update image.

  1. Once the update image is copied to the device, The update of the operating system can be started and installed manually using cc-update binary:

$ sudo cc-update install CCpilot-V700-x.x.x.x-os-update-bundle.raucb

  1. Soon after the start of the update a short beep will be heared and the led will start blinking Yellow until the update is finished.

  2. On successful update of the device, the led will be turned Green and a long beep for 2 seconds will be heared. If the update is unsuccessful, then the led will blink Red with audible falling tone beeps and then turned Green for the system to be updated again.

  3. After successful update, the device will be rebooted automatically by the cc-update binary.

  4. Verify the system is booted up with the updated image after the reboot.

Warning

Either by automatic software update or by manual software update, If the software in the device and the software to be updated are the same, then the update will be not be performed and will simply fail. So, make sure the software to be updated is different from the software in the device.

7.4.3 Update logs

On both automatic and manual update of the operating system, the update logs will be stored in /data/rauc/install.log.

The content of the install.log file will look like:

$ sudo cat /data/rauc/install.log
2024-11-20T09:30:20Z: Installation b320d1e8 started
2024-11-20T09:30:20Z: Updating slot rootfs.1
2024-11-20T09:30:28Z: Installation b320d1e8 successful