Updating Your Sol3

Sol3 base units run a customized Android operating system, Sol3 OS, and are managed using the sol3-manage tool. The sol3-manage tool is distributed via docker container, and should be run using the following script in sol3-sdk:

./sol3-sdk/scripts/sol3_manage --help

sol3-manage supports multiple methods of connection to a base unit, including ADB (via USB) and SSH. To see all the commands and options provided by sol3-manage pass -h or --help to the program.

Updating the System Over-the-Air

Sol3 OS updates for the system image are performed via a minimal binary patch, with rollback support.

Note

The first time you run an update command on a particular host you will be prompted to create a GitHub token which gives sol3-manage access to the space-ng/sol3-sdk GitHub repository where the Sol3 OS releases are present.

Important

When using SSH you will prompted for a password many times unless you add your host’s ssh key as authorized on your Sol3: ssh-copy-id dev@<sol3-ip>. This should be done before running the update command over SSH.

To update a Sol3 base unit with sol3-manage, use the update command:

./sol3-sdk/scripts/sol3_manage -p ssh://dev@<sol3-ip> update <version>

This command will connect to the Sol3 base unit over SSH, download the update from the space-ng/sol3-sdk GitHub repository, and apply it on the remote device. After the update is applied, you will be prompted to select an action. The chosen action determines whether the base unit will immediately reboot into the updated OS.

Confirming the Update

Note

If you are using SSH, the update command may prompt you to confirm the update automatically. If you accept this prompt, you do not need to manually confirm.

After rebooting into your updated version of the Sol3 OS, you must confirm the update. This marks the updated OS as the default OS version for future boots. If the update does not go as planned and you do not confirm, the OS will revert back to the previous version on the next reboot.

./sol3-sdk/scripts/sol3_manage -p ssh://dev@<sol3-ip> remote confirm

Flashing a Sol3: Managing the Recovery and Partitioning

Attention

General system updates do not require flashing. Flashing should be done when specifically called out in release notes, when specifically recommended during support discussions, or if intending to reset the device to a factory state.

Flashing of devices is also performed with sol3-manage, but unlike OTA system updates requires a direct ADB connection via USB. In order to connect over ADB you must know your device’s serial number. To get your device’s serial number, use the list-devices command:

./sol3-sdk/scripts/sol3_manage -p local list-devices

If you see multiple devices reported here, unplug any other Sol3 or android devices from your machine, and rerun the command. You make also need to run adb kill-server on your host machine if you have adb installed. Once you have your serial number, it is perfectly safe to run sol3-manage commands with multiple devices plugged in.

Note

When performing the following steps the device may be put into fastboot mode, a state in which the device will only respond to fastboot commands. It is expected that you can’t communicate with the device as you normally would. To exit back to the default operating mode, use the reboot-adb command of sol3-manage. It is important that you only exit fastboot mode once the device is back into a healthy state, in other words do not skip any steps in the following sections.

Updating the Recovery Partition

To update a Sol3 base unit’s recovery partition, use the update-recovery command:

# First, put the device into fastboot mode.
./sol3-sdk/scripts/sol3_manage -p adb://<sol3-id> reboot-fastboot

# This command may fail a few times before succeeding, as the device
# takes a few seconds to come back online after the previous command.
./sol3-sdk/scripts/sol3_manage -p adb://<sol3-id> update-recovery <version>

# Reboot back to adb.
./sol3-sdk/scripts/sol3_manage -p adb://<sol3-id> reboot-adb

These commands will connect to the Sol3 base unit over USB, put the device into fastboot mode, download the update from the space-ng/sol3-sdk GitHub repository, create an ext4 filesystem, and flash it to the recovery partition.

Clearing Data

Caution

Clearing the data WILL destroy any data present on the device, and should only be done once all important data is backed up from the device. In addition it will require updating the device, as the OS is stored in the data partition as well.

You can forcefully clear and reformat the data partition on the device using the following command:

# First, put the device into fastboot mode.
./sol3-sdk/scripts/sol3_manage -p adb://<sol3-id> reboot-fastboot

# This command may fail a few times before succeeding, as the device
# takes a few seconds to come back online after the previous command.
./sol3-sdk/scripts/sol3_manage -p adb://<sol3-id> clear-data

# Reboot back to adb.
./sol3-sdk/scripts/sol3_manage -p adb://<sol3-id> reboot-adb

Repartitioning

Repartitioning the device, which in general should not be required, will ensure that the partitions on your Sol3 are setup to maximize the space available for use. This process only needs to be done once per device, and will fail at the repartition step if the device is already repartitioned.

Caution

Repartitioning the device also entails clearing ALL data present on the device and updating the recovery image, and should only be done once all important data is backed up from the device. It is important to complete each step in order, and to ensure each command succeeds before you proceed to the next command. It is expected that some commands may need to be rerun due to limitations of Docker. See the comments above each command.

# First, put the device into adb mode.
./sol3-sdk/scripts/sol3_manage -p adb://<sol3-id> reboot-adb

# Repartition the device to the new layout.
# This command may fail a few times before succeeding, as the device
# takes a few seconds to come back online after the previous command.
./sol3-sdk/scripts/sol3_manage -p adb://<sol3-id> repartition

# Next enter fastboot mode.
./sol3-sdk/scripts/sol3_manage -p adb://<sol3-id> reboot-fastboot

# Update the recovery partition to ensure that it is healthy.
# This command may fail a few times before succeeding, as the device
# takes a few seconds to come back online after the previous command.
./sol3-sdk/scripts/sol3_manage -p adb://<sol3-id> update-recovery <version>

# Run clear-data to ensure the data partition is correctly set up
./sol3-sdk/scripts/sol3_manage -p adb://<sol3-id> clear-data

# Reboot back to adb. At this point you probably want to do a
# OTA system update as described above
./sol3-sdk/scripts/sol3_manage -p adb://<sol3-id> reboot-adb