README.md 4.51 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

SWUpdate is a Linux Update agent with the goal to
provide an efficient and safe way to update
David Mondou's avatar
David Mondou committed
5
an embedded system. 
David Mondou's avatar
David Mondou committed
6
7
8
9
10
11
12
13
14

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.

David Mondou's avatar
David Mondou committed
15
An update package is described by the sw-description file.
David Mondou's avatar
David Mondou committed
16
17
18
19
20
21
22
23
24
25
26
27
28

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+

Mick Michalski's avatar
Mick Michalski committed
29

Mick Michalski's avatar
Mick Michalski committed
30
## Connecting a Rigado Gateway to Rigado DeviceOps:
Mick Michalski's avatar
Mick Michalski committed
31

32
**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.
Mick Michalski's avatar
Mick Michalski committed
33

34
**2:** When creating an update for the gateway, include one of the following lua scripts in your `sw-description` file:
Mick Michalski's avatar
Mick Michalski committed
35

36
37
38
- `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)
Mick Michalski's avatar
Mick Michalski committed
39

40
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.
Mick Michalski's avatar
Mick Michalski committed
41

42
You can find examples of how to include these scripts in your `sw-description` file below.
Mick Michalski's avatar
Mick Michalski committed
43

44
**3:** Set the installation device to one of the following:
Mick Michalski's avatar
Mick Michalski committed
45

46
47
- `/dev/dev-k` (for the kernel)
- `/dev/dev-fs` (for the filesystem)
Mick Michalski's avatar
Mick Michalski committed
48

49
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.
Mick Michalski's avatar
Mick Michalski committed
50
51
52
53
54
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

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