# 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. 

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.

Here a short list of the main features:

- Install on embedded media (eMMC, SD, Raw NAND, NOR and SPI-NOR flashes)
- Multiple interfaces for getting software
    - local storage
    - integrated REST client connector to [hawkBit](https://projects.eclipse.org/projects/iot.hawkbit)
- Software delivered as images, gzipped tarball, etc.
- Power-Off safe
- Hardware / Software compatibility.

This software is licensed under GPL Version 2.0+


## Connecting a Rigado Gateway to Rigado DeviceOps:

**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`.