Project

General

Profile

Users Guide » History » Version 39

Hammel, 25 Sep 2019 16:43

1 10 Hammel
h1. Ironman Users Guide
2 1 Hammel
3 7 Hammel
table{border-collapse;width:100%}.
4 8 Hammel
|={font-size:140%;margin-bottom:15px;background-color:#fdd}. This document is under development and is likely not accurate at this time. |
5 7 Hammel
6 2 Hammel
{{>toc}}
7
8 34 Hammel
In this document the term _host system_ refers to a Linux desktop or laptop that will be used to download and install software onto an SD card.
9 1 Hammel
10 10 Hammel
h2. Overview
11
12 17 Hammel
_*Ironman*_ is a home automation project based on the PiBox build system.  It supports a Nest-like monitor for controlling Arduino based sensors, cameras and remote voice control.
13 1 Hammel
14
|!http://redmine.graphics-muse.org/attachments/download/114!|
15
|={font-size:120%;margin-bottom:15px;background-color:#dff}. *Design Intent of the Ironman Project* |
16
|=. Mark I release is in progress.  Mark II and Mark III are future development plans.|
17
18 17 Hammel
_*Ironman*_ consists of the following components.
19 12 Hammel
20
| *Monitor* | The Nest-like control hub based on a Raspberry Pi 2/3 and the official 7" touchscreen display |
21
| *Sensors* | Arduino based devices, such as door alarms and cameras, running code based on a sensor and camera templates for pairing and secure communication with the Monitor |
22
| *Jarvis*  | A Java application that supports voice control of Monitor managed devices |
23
| *Controllers* | Network enabled control of Monitor managed devices |
24
25 1 Hammel
h3. Security
26
27 17 Hammel
_*Ironman*_ supports AES encrypted communication with IoT sensors and Jarvis interfaces.
28 12 Hammel
29
h3. What it is
30
31 17 Hammel
_*Ironman*_ is a do-it-yourself system, where you buy the parts and assemble them as described, modifying the provided code to suit your needs and handling flashing and maintenence.  _*Ironman*_ is designed to allow you to build your own home automation system where you specify the devices you want to control and how you want to control them.  
32 12 Hammel
33
h3. What it is not
34
35 17 Hammel
_*Ironman*_ is not a product.  It is not intended for anyone other than Makers (aka DIY'ers) who like to tinker and see not just how to assemble things but why they actually work.
36 12 Hammel
37 17 Hammel
While the Users Guide is intended to bring up a currently working version of _*Ironman*_ with limited sensor and camera support, if you aren't prepared to deal with writing code or flashing devices and dealing with electrical circuits then _*Ironman*_ is not for you.
38 10 Hammel
39 1 Hammel
h2. The Ironman Monitor
40 3 Hammel
41 17 Hammel
The _*Ironman*_ Monitor runs on a Raspberry Pi 2 or 3 and provides a central hub for management of home automation devices.  It uses a 7" touch screen display and a mechanical switch to manage pairing with IoT devices and Jarvis interfaces.
42 3 Hammel
43
h3. Installation Prerequisites
44 1 Hammel
45 11 Hammel
* A "Raspberry Pi 2 or 3":https://www.adafruit.com/product/3055
46
* The official "Raspberry Pi 7inch touchscreen display":https://www.sparkfun.com/products/13733
47
* The Pi 2/3 requires a "V / 2A power supply":https://www.adafruit.com/product/1994.  For best results, use a power supply rated to at least 5.25V to avoid under voltage conditions.  For ease of use the power supply cable should include an "on/off switch":https://www.adafruit.com/product/2379.
48 27 Hammel
* A keyboard is required for initial installation.  A "wireless keyboard":https://www.adafruit.com/product/922 should work as will a wired keyboard.  The keyboard will not be needed for normal operation but can be helpful in debugging.
49 3 Hammel
* The Pi 2/3 requires a microSD card that is at least 4GB.  A mechanism for using the SD card on your host system is needed, such as an SD card USB adapter or an SD port on your laptop.
50 32 Hammel
* A mechanical switch, such as a "SPDT":https://www.electronicshub.org/switches/#Single_Pole_Double_Throw_Switch_SPDT, should be connected to the Pi GPIOs to allow for pairing the Monitor with IoT Sensors and Jarvis interfaces.  The ASCII diagram below describes the setup. The LED is off in normal mode, lit in Config Mode, and off in Pair Mode until something tries to pair with the Pi which then turns on the LED for 3 seconds. Config and Pair mode operations ared discussed in later sections.  A Fritzing Diagram (attachment:IronmanMonitorSwitch.fzz) is available for this hardware component.
51 30 Hammel
!>{width:300px}IronmanMonitorSwitchBreadboard.png(Ironman Monitor Switch)!
52 1 Hammel
<pre>
53 16 Hammel
                      ___
54
   Config/Pair Mode  |---|  Normal Mode
55
                   --------- 
56
                  |         |
57
                   --------- 
58
connector pins -->  |  |  |  
59
                    |  |   ------ Not connected
60
                    |  |
61
                    |  ----330 Ohm R-----
62
                    |  |                |
63
                    |  |  +-----LED------
64
                    |  |  |
65
          RPi pin   7  9  13     
66
         RPi GPIO   4  G  27
67 6 Hammel
</pre>
68 5 Hammel
69 27 Hammel
* You will need to have sudo access for your Linux user id.
70 16 Hammel
71 1 Hammel
h3. Generating the SD Card for the Pi
72 3 Hammel
73 1 Hammel
* Download the RPi 2 Development Platform 
74 4 Hammel
** _wget <url>_
75
** Unpack the archive to a directory called *image*.
76 17 Hammel
* Download the _*Ironman*_ Package Collection
77 4 Hammel
** _wget <url>_
78 1 Hammel
** Unpack the archive to a directory called *package*.
79 18 Hammel
* In a terminal window run: _dmesg -w_
80
* Insert the microSD card and note the device name displayed for the newly added card as displayed in the _dmesg -w_ terminal window.  It should be something like /dev/sdb or /dev/sde.
81
* Kill the _dmesg -w_ command with Ctrl-C.
82 4 Hammel
83
From the *image* directory
84 1 Hammel
* Format the SD card
85
** _sudo ./mksd.sh -d <device name>_
86 18 Hammel
** where <device name> is the name you noted from the output of _dmesg -w_.
87 3 Hammel
* Mount the boot partition from the sd card: 
88 4 Hammel
** _sudo mkdir -p /mnt/boot_
89
** _sudo mount <device name>1 /mnt/boot_
90 18 Hammel
** where <device name> is the name you noted from the output of _dmesg -w_.
91 4 Hammel
* Install the Development Platform to the SD card
92
** _sudo ./mkinstall.sh -b /mnt/boot -d <device name>2_ 
93 18 Hammel
** where <device name> is the name you noted from the output of _dmesg -w_.
94 3 Hammel
95 4 Hammel
From the *package* directory
96 3 Hammel
* Mount the root partition from the sd card: 
97 4 Hammel
** _sudo mkdir -p /mnt/root_
98
** _sudo mount <device name>1 /mnt/root_
99 17 Hammel
* Copy the _*Ironman*_ Package Collection files to /root of the root partition on the SD card
100 4 Hammel
** _sudo cp *.opk /mnt/root/root_
101 3 Hammel
102
Make sure all writes to the SD card have completed
103 4 Hammel
* _sync;sync;sync_
104 3 Hammel
105
Unmount the SD card partitions
106 4 Hammel
* _sudo umount /mnt/boot_
107
* _sudo umount /mnt/root_
108 3 Hammel
109 4 Hammel
Remove the SD card from the host system and insert it into the Raspberry Pi 2.
110 1 Hammel
111
h3. First time boot
112
113 26 Hammel
Power on the Monitor and wait for it to complete installation.  During this time the display may be upside down.  Once initial installation is complete the display will be right side up.
114 22 Hammel
115
Once the display shows two xterm windows it is ready to complete installation.  Type the following command to install the _*Ironman*_ package collection.
116
117
  opkg install *.opk
118
119
Wait for this command to complete, then reboot the system either by power it off and back on or by typing the command 
120
121
  reboot
122
123
The Monitor is now fully installed and ready for use.
124
125
h3. First time configuration
126
127 33 Hammel
!>{width:300px}ironman-config-ui.png(Ironman Config UI)!
128 24 Hammel
129 22 Hammel
Turn the power off and set the Mode switch to Config/Pair, then power the Monitor back on.  The LED should light indicating the Monitor is ready to be configured.
130
131
Use a smartphone or laptop with wifi to connect to the "ironman" SSID.  The default password is _ironman1_.  Then use a browser to connect to the Ironman web UI at 
132
133
  http://192.168.36.1:1337
134
135 25 Hammel
The display should be as shown in the adjacent photo.  There are two network domains to configure, as described in the following table.
136
137
|_. Domain |_. Description |
138
| Internet Connection | This is how the Monitor will connect to your home network. |
139
| Sensors Network | This is how the Monitor will communicate with your IoT devices. |
140 22 Hammel
141 36 Hammel
After both networks are configured, power off the Monitor and set the Mode switch to Normal, then power the Monitor on.  The Monitor is now ready to use with IoT sensors, Jarvis and controllers.
142
143 1 Hammel
h3. Network configuration
144
145 34 Hammel
The Monitor's hardware supports WiFi B/G/N networks.  However, in order to use the Monitor as both a WiFi client on the local
146
network and as an Access Point for IoT devices, only G networks are supported by the Ironman software.
147
148
h4. Internet Connection
149
150
The Internet Connection domain configures the Monitor to connect to your local network.  
151
152
|_. Field |_. Description |
153
|Location |Unique name for this monitor, such as Bedroom or Office.  This name is used to identify monitors by name via commands from Jarvis or other remote controllers|
154
|SSID |Network name configured on your router for your local WiFi network. |
155
|Security | Type of security used on your router. Only WPA2 Personal and WPA2 Enterprise are currently supported. |
156
|Password | Your router's password, specifically for the SSID entered previously. |
157
158
The *Show Password* button will display the password typed in the Password field.  By default this button is not enabled, causing the Password field to be hidden using asterisks for each character.
159
160
h4. Sensor Network
161
162
The Sensor Network domain is used to configure the Monitor's private network used with IoT devices.  Data on this network is not routed to the Internet Connection and data from the Internet Connection domain are not routed to the Sensor Network.
163
164
|_. Field |_. Description |
165
|SSID |Network name for this private WiFi network. This name will be hidden on Wifi scans.|
166
|Channel | Channel to use.  Select a channel that has low use in your neighborhood.  Only a subset of channels on G networks are available.  This will be addressed in future releases. |
167
|Password | Password IoT devices should use to gain access to the specified SSID. |
168
|Static IP | An IP address to give the Monitor as it acts as an Access Point. This should be a Class C subnet for the network, which limits the number of IoT devices that can be managed by a single Monitor to 254. |
169
170
The *Show Password* button will display the password typed in the Password field.  By default this button is not enabled, causing the Password field to be hidden using asterisks for each character.
171
172 38 Hammel
h2. IoT Sensor
173 1 Hammel
174 38 Hammel
h3. Sensor Types
175
176
There is currently only one sensor type:  imlightsw (light switch).  
177
178
The sensor template GIT repository is intended to be used to design additional sensor types, such as door and window alarms, window shade controllers, environment sensors and so forth.
179
180
h4. Light Switch
181
182
<pre>
183
TBD: show screenshot of fritzing diagram for light switch board.
184
</pre>
185
186
h3. Flashing the firmware
187
188
<pre>
189
TBD: show screenshot of fritzing diagram for flashing board.
190
</pre>
191
192
h3. Power On
193
194 37 Hammel
An IoT sensors must be configured to operate on the same network as the Monitor's Sensor Network.  Once this has been done the IoT sensor and the Monitor can be paired.  An IoT device can only be paired with a single Monitor.
195 14 Hammel
196
h4. Configuring an IoT Device Network
197
198
* Set the Mode button to Config. 
199 1 Hammel
* Power on the IoT device.
200
* TBD
201
202 38 Hammel
h3. Pairing with a Monitor
203 14 Hammel
204 38 Hammel
* With the Monitor running, set the Monitor Mode switch to Pair.
205 14 Hammel
* Power on the IoT Sensor and wait for it to pair with the Monitor.  When it's done, the LED will light for 3 seconds.  
206
* Disable the Mode switch on the Monitor.
207
208 9 Hammel
table{border-collapse;width:100%}.
209
|={font-size:140%;margin-bottom:15px;background-color:#fdd}. *WARNING!* |
210 1 Hammel
|={font-size:120%;margin-bottom:15px;background-color:#fdd}.  Leaving the Mode switch turned to Pair will allow random devices to attempt to pair with the Monitor.  This is a security risk.  The Mode switch should only be set to Pair long enough to pair with an IoT device. |
211
212
h2. Jarvis
213
214
h3. Prerequisites
215
216
h3. Pairing with a Monitor
217 38 Hammel
218
* With the Monitor running, set the Monitor Mode switch to Pair.
219
* TBD
220 1 Hammel
221
h3. Supported Commands
222
223 35 Hammel
h2. Addendums
224
225
h3. Ironman Apps
226
227
|_. App |_.Contents |_. Description |
228
|imcore | |Package that updates a PiBox Development Platform for use with Ironman.  Includes network configuration updates and other config files. |
229
|imwww | |Contains two web servers |
230
| |imwww |Provides network configuration interface for Monitor |
231
| |imrest |Provides IoT/Jarvis REST API.  Updates /etc/ironman directories with registrations.|
232
|imgpio | |Command line tool for querying GPIO pins using syfs interface. |
233
|launcher | |Ironman specific launcher that adds clock interface to front panel. |
234
|pisensors | |Provides UI for managing sensors.  Uses inotify to watch for changes to /etc/ironman/iot directory. |
235
|picam | |Generic console camera interface (same as PiBox media systems) |
236 1 Hammel
|Misc |appmgr, piboxd, omxplayer, pmsui, psplash, mjpg-streamer| Same packages as in PiBox media system, unmodified|
237
238
h3. Source Code Repositories
239
240
* PiBox
241 39 Hammel
** "Development Platform":https://gitlab.com/pibox/pibox
242
** "appmgr":https://gitlab.com/pibox/appmgr
243
** "mjpg-streamer":https://gitlab.com/pibox/mjpg-streamer
244
** "omxplayer":https://gitlab.com/pibox/omxplayer
245
** "piboxd":https://gitlab.com/pibox/piboxd
246
** "picam":https://gitlab.com/pibox/picam
247
** "pmsui":https://gitlab.com/pibox/pmsui
248
** "psplash":https://gitlab.com/pibox/psplash
249 1 Hammel
* Ironman
250 39 Hammel
** "gpio":https://gitlab.com/xironman/gpio
251
** "launcher":https://gitlab.com/xironman/launcher
252
** "monitor":https://gitlab.com/xironman/monitor
253
** "pisensor":https://gitlab.com/xironman/sensors
254
** "www":https://gitlab.com/xironman/www
255
** "meta build":https://gitlab.com/xironman/meta
256 1 Hammel
* Arduino
257 39 Hammel
** "Sensor Template (imlightsw)":https://gitlab.com/xarduino/lightsw
258
259 1 Hammel
260
h3. Fritzing Models
261
262
* ESP-01 Flasher
263
* Light Switch
264 35 Hammel
** Keyes_SRly
265
** Hilink
266
* Monitor Switch: attachment:IronmanMonitorSwitch.fzz
267
268
h3. Networking Internals
269
270
<pre>
271
wlan0
272
273
* This interface is used for configuration of the Monitor.
274
* Configured on the 192.168.36.0 subnet.
275
** See /etc/network/dhcpd.conf.aponly
276
277
uap0
278
279
* This interface is used as an access point for IoT devices.
280
* Configured on the 192.168.3.0 subnet.
281
** See /etc/network/dhcpd.conf.uap and dhcpd.conf.uap.tmpl
282
** The template is used to change the base subnet through the web interface.
283
** The SSID is _ironman_.
284
</pre>
285
286
h3. Pair Button Usage
287
288
<pre>
289
Pair/Config button is GPIO 4 (RPi pin 7)
290
Pair/Config LED is GPIO 7 (RPi pin 13)
291
	LED should only be lit on boot if button is enabled (in Config mode).
292
		In this case, we're in Config Mode to configure the networks.
293
		The web server (imwww) is on SSID _ironman_ at 192.168.36.1:1337.
294
	LED is off on boot if button is disabled (in Pair Mode).
295
	If in Pair Mode
296
		Start hostapd for aponly
297
		Start dhcpd for aponly on wlan0
298
		Start imrest web service on port 8165 for IoT devices and Jarvis interfaces.
299
	If in Config Mode
300
		Start wpa_supplicant on wlan0
301
		Create uap0 device as virtual device on wlan0
302
		Start dhcpd on uap0
303
		Start hostapd on uap0
304
		Start imwww for network configuration of the Monitor.
305
</pre>
306
307
h3. Monitor IoT Directories
308
309
<pre>
310
/etc/ironman/iot		Registration directory for IoT devices
311 1 Hammel
/etc/ironman/jarvis		Registration directgory for Jarvis interfaces
312
</pre>