The Circle will automatically check for firmware updates, and install them if it’s between 1am and 4:59am local time.
It is also possible to “push” a firmware update image to the device (at any time), with the limitation being that the ‘source IP address’ of the computer pushing the update must be on the “10.123.234.xx” subnet (that is the subnet used by the default Circle Wifi AP before it is associated with your router). I’ve only done the firmware update “push” before the Circle was associated with my router. I suppose if I reconfigured my router to use the “10.123.234.xx” subnet (and hand-out DHCP addresses there), it would be possible to push firmware updates after it’s been associated.
Firmware updates are AES-encrypted gzipped .tar files. Below is the part of the “/mnt/shares/usr/bin/firmware_updater.sh” that does the decrypt and install:
#update firmware if [ "$firmware_ver" != "0.0" -a "$my_firmware_ver" != "$firmware_ver" ] ; then cd /mnt; rm -f update_firmware.sh; rm -f /mnt/firmware.bin; echo fastblink > /tmp/blueled; /tmp/wget -q -O /mnt/firmware.bin "http://download.meetcircle.co/dev/firmware/get_firmware.php?DEVID=$MAC$EXTRA&ENCRYPT=1" if [ -f /mnt/firmware.bin ] ; then aescrypt -d -o - /mnt/firmware.bin | gunzip -c | tar xf - if [ -f /mnt/update_firmware.sh ] ; then mkdir -p /mnt0 mount -t ext4 -o rw,noatime,nodiratime /dev/sda2 /mnt0 && rm -f /mnt0/firmware.bin && cp /mnt/firmware.bin /mnt0 && umount /mnt0 rm -f /mnt/firmware.bin; sh /mnt/update_firmware.sh exit 0 fi rm -f /mnt/firmware.bin; fi echo "error downloading and installing firmware" exit 1 else echo "not updating firmware: firmware_ver=$firmware_ver my_updater_ver=$my_firmware_ver"; fi
As you can see, the new “/mnt/firmware.bin” file is decrypted and passed through gunzip/tar, directly on top of the “/mnt” filesystem (“/dev/sda3” ext4 filesystem on eMMC).
The “aescrypt” command is a customized version of the open-source utility available here: https://www.aescrypt.com. Circle’s primary customization is to use a hard-coded password (normally, you have to use either the “-p” option to specify a password, or “-k” to specify a key file – they use neither in their command above).
After the untar is finished, it mounts “/dev/sda2” and copies the encrypted “/mnt/firmware.bin” to that partition. I believe this partition is used for a failsafe/recovery in case of corruption (or maybe just for any factory reset).
After that, the script “/mnt/update_firmware.sh” (which was at the top-level inside the “/mnt/firmware.bin” tar file) is run. Normally, this script just does a “reboot” of the device.
It’s possible to create a modified firmware image with a customized “/mnt/update_firmware.sh” (where you can do whatever you want, such as installing new “passwd” and “shadow” files). As a matter of fact, you can create a firmware update image which only contains an “update_firmware.sh” script at the top-level (no other ‘firmware’ inside), but keep in mind that this image will be copied to the ‘failsafe/recovery’ partition, and if it doesn’t include a full firmware image, you could be left with a ‘bricked’ device.
Downloading your own firmware from Circle:
If you want to download your own firmware image (for reverse-engineering/poking around), you can. Below is the command that the Circle device uses to pull-down a new (encrypted) firmware image:
/tmp/wget -q -O /mnt/firmware.bin "http://download.meetcircle.co/dev/firmware/get_firmware.php?DEVID=00:00:00:00:00:00&HWVER=1&ENCRYPT=1"
“DEVID” is the MAC address of your Circle device – I’ve found that it’s OK to specify all zeros. As a matter of fact, you don’t need to specify it at all:
wget -O firmware.bin "http://download.meetcircle.co/dev/firmware/get_firmware.php?HWVER=1&ENCRYPT=1"
aescrypt -d -k KEYFILE.dat -o firmware_decrypted.bin firmware.bin
After executing the above command, you will have a “firmware_decrypted.bin” (which is really a gzip-compressed .tar)
As I said, you can modify the firmware (for example, modify “update_firmware.sh” to add your own customization), then encrypt it with the “-e” option.
Pushing your own firmware update to the Circle:
Here’s a “curl” command to push an encrypted firmware image (“firmware.bin”) to your Circle device:
curl -k -F "firstname.lastname@example.org;filename=nameinpost" https://10.123.234.1:4567/api/UPLOAD_FIRMWARE
As I said, the UPLOAD_FIRMWARE API command only works when sent from a computer on the 10.123.234.xxx subnet (the subnet used by the Circle before it is associated with your router).
More details later…