README.md 5.52 KB
Newer Older
Mick Michalski's avatar
Mick Michalski committed
1
# SWUpdate - Software Update for Embedded Systems
David Mondou's avatar
David Mondou committed
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

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

Mick Michalski's avatar
Mick Michalski committed
42
## Submitting patches
David Mondou's avatar
David Mondou committed
43
44
45
46
47
48
49
50
51
52
53
54

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 <revision range>

Please use 'git send- email' to send the generated patches to the ML
to bypass changes from your mailer.
Mick Michalski's avatar
Mick Michalski committed
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168

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