# SWUpdate - Software Update for Embedded Systems SWUpdate is a Linux Update agent with the goal to provide an efficient and safe way to update an embedded system. SWUpdate supports local and remote updates, multiple update strategies and it can be well integrated in the [Yocto](https://www.yoctoproject.org) build system by adding the [meta-swupdate](https://layers.openembedded.org/layerindex/branch/master/layer/meta-swupdate/) layer. It supports the common media on embedded devices such as as NOR / NAND flashes, UBI volumes, SD / eMMC, and can be easy extended to introduce project specific update procedures. Pre- and postinstall scripts are supported, and a LUA interpreter helps to customize the update process. An update package is described by the sw-description file, using the libconfig syntax or JSON. It is even possible to use LUA with a custom syntax. Here a short list of the main features: - Install on embedded media (eMMC, SD, Raw NAND, NOR and SPI-NOR flashes) - Allow delivery single image for multiple devices - Multiple interfaces for getting software - local storage - integrated web server - integrated REST client connector to [hawkBit](https://projects.eclipse.org/projects/iot.hawkbit) - remote server download - Software delivered as images, gzipped tarball, etc. - Allow custom handlers for installing FPGA firmware, microcontroller firmware via custom protocols. - Power-Off safe - Hardware / Software compatibility. This software is licensed under GPL Version 2.0+ Please check inside doc directory for documentation or the online documentation (generated from doc/) at: http://sbabic.github.io/swupdate ## Submitting patches You can submit your patches (or post questions reagarding the project to the swupdate Mailing List: swupdate@googlegroups.com When creating patches, please use something like: git format-patch -s Please use 'git send- email' to send the generated patches to the ML to bypass changes from your mailer. ## Gateway Update Instructions: **1:** When the gateway is first started, you will need to update the config file at `/etc/gateway.conf`, with the proper settings for your servers. Any file system updates should contain a new, properly configured `gateway.conf` file along with the updates. Reboot the gateway to implement the changes. **2:** When creating an update for the gateway, include one of the following lua scripts in your `sw-description` file: - `prepost-k.lua` (if updating the kernel) - `prepost-fs.lua` (if updating the file system) - `prepost-kfs.lua` (if updating both the kernel and filesystem) These Lua scripts call applications on the installed system that prepare the system for install. After a successful install, they will update the system to boot into the newly updated partitions. You can find examples of how to include these scripts in your `sw-description` file below. **3:** Set the installation device to one of the following: - `/dev/dev-k` (for the kernel) - `/dev/dev-fs` (for the filesystem) These are the devices that are referenced in the `sw-description` file. They will be created by the applications that the Lua scripts execute. See the examples below for how to set these in your updates. ### Example sw-description files: #### Updating the filesystem only: software = { version = "3.1"; hardware-compatibility = [ "2.0" ]; files: ( { filename = "myNewFilesystem.tar.gz"; path = "/"; device = "/dev/dev-fs"; filesystem = "ext3"; compressed = "true"; type = "archive"; } ); scripts: ( { filename = "prepost-fs.lua"; type = "lua"; } ); } #### Updating the kernel and filesystem: software = { version = "3.1"; hardware-compatibility = [ "2.0" ]; images: ( { filename = "myNewKernel.dtb"; device = "/dev/dev-k"; type = "flash"; } ); files: ( { filename = "myNewFilesystem.tar.gz"; path = "/"; device = "/dev/dev-fs"; filesystem = "ext3"; compressed = "true"; type = "archive"; } ); scripts: ( { filename = "prepost-kfs.lua"; type = "lua"; } ); } #### Example gateway.conf file: # The tenant for swupdate: export SURICATTA_TENANT="default" # The URL to connect to export SURICATTA_URL="http://super-ops.com" # The unique device id export SURICATTA_ID="device-1234" # The norflash device to write settings to export DEVICE_SETTINGS="/dev/mtd0" # The partitions to use for the kernel export DEVICE_KERNEL_MAIN="/dev/mtd1" export DEVICE_KERNEL_ALT="/dev/mtd2" # The partitions to use for the file system export DEVICE_FILESYSTEM_MAIN="/dev/mmcblk1p2" export DEVICE_FILESYSTEM_ALT="/dev/mmcblk1p3" ### Things to watch out for: The `SURICATTA_ID` is used inside an URL. Only use URL safe characters. The file names used in the swu file must be under 40 characters each. Otherwise you may get a "`SWUPDATE failed [1] Image invalid or corrupted. Not installing ...`" error. The generated file `/etc/hwrevision` contains the `boardname` and `revision`. The `revision` is the value to use for `hardware-compatibility`.