Project

General

Profile

Statistics
| Branch: | Revision:

gdp-if / i3mote / README.md @ master

History | View | Annotate | Download (10.7 KB)

1 86319936 Rick Pratt
<!-- Use "pandoc -sS -o README.html README.md" to process this to HTML -->
2
3
# GDP Software User Guide for TI i3mote sensors and BeagleBone Black Gateway
4
5
## Prerequisites
6
7
* BeagleBone Black hardware, connected to the Internet
8
* Debian 8 operating system installed
9
* DHCP server providing BeagleBone Black IP address assignment
10
* Password-less sudo access by the "debian" user account
11
12 67985f36 Nitesh Mor
A *New BeagleBone Black* Setup Guide is appended to these instructions, with
13
notes on setting up a BeagleBone Black from scratch.
14 86319936 Rick Pratt
15
## Acquire and Compile Required Software
16
17 67985f36 Nitesh Mor
The BeagleBone will require GDP library, libcoap, the CoAP=>GDP gateway, and TI
18
software.
19 86319936 Rick Pratt
20
Clone the main GDP repository:
21
22
~~~
23
$cd ~ && git clone https://repo.eecs.berkeley.edu/git-anon/projects/swarmlab/gdp.git
24
~~~
25
26
Install the necessary packages required for compilation:
27
28
~~~
29
$ cd ~/gdp/adm && sudo ./gdp-setup.sh
30
~~~
31
32
Compile and install the client side:
33
34
~~~
35
$ cd ~/gdp && make
36
$ cd ~/gdp && sudo make install-client install-python
37
~~~
38
39
Make sure that the default routers are setup appropriately:
40
41
~~~
42
$ sudo mkdir /etc/ep_adm_params
43
$ sudo bash -c "echo 'swarm.gdp.routers=gdp-01.eecs.berkeley.edu; gdp-02.eecs.berkeley.edu; gdp-03.eecs.berkeley.edu; gdp-04.eecs.berkeley.edu' >> /etc/ep_adm_params/gdp"
44
~~~
45
46 67985f36 Nitesh Mor
Clone the GDP-IF (or "GDP Interfaces") repository, which primarily consists of
47
GDP applications and gateways.  Certain setup scripts for some of the software
48
will assume the location of this repository to be inside the gdp directory.
49 86319936 Rick Pratt
50
~~~
51
$ cd ~/gdp/ && git clone https://repo.eecs.berkeley.edu/git-anon/projects/swarmlab/gdp-if.git uhb
52
~~~
53
54 67985f36 Nitesh Mor
Acquire libcoap and compile it. Avoid building the documentation
55
(`--disable-documentation` parameter), because it requires way too many
56
dependencies for the limited disk space on a BeagleBone.
57 86319936 Rick Pratt
58
~~~
59
$ sudo apt install unzip
60
$ mkdir ~/libcoap
61
$ cd ~/libcoap && wget https://github.com/obgm/libcoap/archive/master.zip && unzip master.zip
62
$ cd ~/libcoap/libcoap-master && ./autogen.sh && ./configure --disable-documentation && make
63
~~~
64
65
Start collecting the necessary components a single directory:
66
67
~~~
68
$ cp -a ~/gdp/uhb/i3mote ~
69
$ cp -a ~/libcoap/libcoap-master/examples/coap-client ~/i3mote/arm-coap-client
70
~~~
71
72 67985f36 Nitesh Mor
Copy TI software to the Beaglebone. TI software must be installed at the
73
following paths:
74 86319936 Rick Pratt
75 67985f36 Nitesh Mor
* Gateway executable: `/home/debian/gwapp.exe`
76
* Node.js web application directory (recursive copy advised):
77
  `/home/debian/webapp`
78 86319936 Rick Pratt
79 67985f36 Nitesh Mor
Verify that the `~/i3mote` directory has the following files to confirm success
80
in the above steps:
81 86319936 Rick Pratt
82 67985f36 Nitesh Mor
* `CoAP-gateway.py`: This is the main wrapper script that (re)starts TI software
83
  and threads (one per physical sensor) for CoAP subscription and data
84
  publishing.
85
* `arm-coap-client`: This is the CoAP client binary from libcoap used by the
86
  `CoAP-gateway.py` script.
87
* `gateway_control.sh`: This is a shell script to start/stop the TI software
88
  (both `gwapp.exe` and `app.js`). The `CoAP-gateway.py` invokes this script for
89
  starting/restarting the TI code. The paths in this script should be updated if
90
  the TI software is not at the assumed location.
91
* `read_csv.py`: This is a script to dump the logged data in a CSV format to a
92
  file.
93 86319936 Rick Pratt
94
## Execution and Log Creation
95
96 67985f36 Nitesh Mor
If the Urban Heartbeat Kit software distribution was installed on this
97
BeagleBone at some point, be sure to stop the gateway-server now:
98 86319936 Rick Pratt
99
~~~
100
$ sudo service gateway-server stop
101
~~~
102
103 67985f36 Nitesh Mor
If the root node and sensors are not yet physically cabled to the BeagleBone
104
with power enabled, then shutdown the BeagleBone, connect a root node and one or
105
more sensors with power enabled, and then power up the BeagleBone, as advised in
106
the I3 Mesh User Guide.
107 86319936 Rick Pratt
108 67985f36 Nitesh Mor
Since a bug exists which can crash the network and require everything to be
109
restarted, it is highly recommended that only `gateway_control.sh` be used for
110
any process control; the following script invocation method saves the
111
process-IDs appropriately and can terminate these processes.  Therefore,
112
presuming the TI software has not already been started by another method, select
113
a site-unique `__SITE_UNIQUE_LOG_PREFIX__` string for the following command
114
specification, where the chosen prefix satisfies the bulleted notes listed below
115
the command:
116 86319936 Rick Pratt
117
~~~
118
$ cd ~/i3mote && ./CoAP-gateway.py ./gateway_control.sh ./arm-coap-client __SITE_UNIQUE_LOG_PREFIX__
119
~~~
120
121 67985f36 Nitesh Mor
* `__SITE_UNIQUE_LOG_PREFIX__` is an installation specific string that will be
122
  used to derive log names. The log names to which individual sensor data is
123
  published are programmatically generated using the sensor EUI64 appended to
124
  this log name prefix. For example, with a prefix
125
  `edu.berkeley.eecs.swarmlab.device` and a sensor with EUI64
126
  `22-12-4b-00-0a-4a-b9-05`, the software will automatically search GDP for a
127
  log named `edu.berkeley.eecs.swarmlab.device.22124b000a4ab905`.
128
* Open a web browser session using the URL `http://<BeagleBone_IP_address>` to
129
  view the BeagleBone-hosted I3-Mesh web site. If only the root node is listed
130
  in the I3-Mesh list, power cycle the root node to trigger discovery of powered
131
  up sensors. Refresh the browser window occasionally to confirm sensor
132
  discovery.
133
* The current setup does not automatically create logs. On the first execution,
134
  `CoAP-gateway.py` will throw a `[Berkeley:Swarm-GDP:600]` (shown below) error,
135
  but the script will also print the GDP log (`<expected_log_name>`) showing the
136
  log name it expects (also shown below), based on the prefix and the available
137
  EUI64's.
138 86319936 Rick Pratt
139
~~~
140 67985f36 Nitesh Mor
New nodes: [(3, u'00-12-4b-00-0c-29-99-01', u'2001:0db8:1234:ffff:0000:00ff:fe00:0003')]
141
>>> Node (00124b000c299901),
142
    IPV6 (2001:0db8:1234:ffff:0000:00ff:fe00:0003),
143
    tmpfile (/tmp/i3mesh-00124b000c299901),
144
    GDP log(edu.berkeley.eecs.swarmlab.device.00124b000c299901),
145
    Subscription statistics(/tmp/00124b000c299901-subscription_stats.log)
146
Exception in thread Thread-1:
147
Traceback (most recent call last):
148
  File "/usr/lib/python2.7/threading.py", line 810, in __bootstrap_inner
149
    self.run()
150
  File "/usr/lib/python2.7/threading.py", line 763, in run
151
    self.__target(*self.__args, **self.__kwargs)
152
  File "./CoAP-gateway.py", line 175, in __processing_thread
153
    __loghandle = gdp.GDP_GCL(gdp.GDP_NAME(self.logname), gdp.GDP_MODE_AO)
154
  File "/usr/local/lib/python2.7/dist-packages/gdp/GDP_GCL.py", line 116, in __new__
155
    check_EP_STAT(estat)
156
  File "/usr/local/lib/python2.7/dist-packages/gdp/MISC.py", line 173, in check_EP_STAT
157
    raise EP_STAT_SEV_ERROR(ep_stat)
158
EP_STAT_SEV_ERROR: 'ERROR: 600 no route available [Berkeley:Swarm-GDP:600]'
159 86319936 Rick Pratt
~~~
160
161 67985f36 Nitesh Mor
* After collecting the necessary GDP log names, stop (control-c) the
162
  `CoAP-gateway.py`
163
* To create GDP logs, run the following command for each GDP log name which was
164
  displayed in the previous step:
165 86319936 Rick Pratt
166
~~~
167 67985f36 Nitesh Mor
$ cd ~/i3mote/ && gcl-create -e none edu.berkeley.eecs.swarmlab.device.22124b000a4ab905
168 86319936 Rick Pratt
~~~
169
170 67985f36 Nitesh Mor
*Note that it is important that `gcl-create` be executed from the correct
171
directory. An auto-generated secret key is stored in the directory that can be
172
later found by the `CoAP-gateway.py` during publishing. Such keys ought to be
173
securely backed up.*
174
175
* Once the logs have been created manually, restart the `CoAP-gateway.py`
176
  process as shown above and leave it running.
177 86319936 Rick Pratt
178 67985f36 Nitesh Mor
Use of a tool like 'GNU screen' or 'byobu' is highly recommended for BeagleBone
179
access using SSH.
180 86319936 Rick Pratt
181
## GDP Log Files
182
183
There are a few log files that may be of interest:
184
185 67985f36 Nitesh Mor
* `/tmp/app.js.log` and `/tmp/gwapp.exe.log`: Console log from the TI software
186
* `/tmp/app.js.pid` and `/tmp/gwapp.exe.pid`: Process IDs of the TI software
187
* `/tmp/*-subscription_stats.log`: A log of CoAP subscriptions to a given
188
  sensor, and the data received relative to the start of CoAP subscription.
189 86319936 Rick Pratt
190
191
# *New BeagleBone Black* Setup Guide
192
193
## *New BeagleBone Black* Hardware Setup
194
195
* Flash the Debian 8 image to the SD card, and then to internal flash storage.
196
> * See instructions on the beagleboard.org and related links.
197 67985f36 Nitesh Mor
> * If the only available SD image does not flash eMMC as part of the SD boot
198
    process, an alternative eMMC flash method is to boot from SD, ssh into
199
    BeagleBone Black via ethernet (DHCP server required), and execute the proper
200
    flasher script interactively. For example:
201 86319936 Rick Pratt
202
~~~
203
user@otherhost$ ssh debian@<dhcp_IP_address_assignment>  (login banner displays password)
204
$ grep init-eMMC-flasher /boot/uEnv.txt
205
#cmdline=init=/opt/scripts/tools/eMMC/init-eMMC-flasher-v3.sh
206
$ cd /opt/scripts/tools/eMMC/
207 67985f36 Nitesh Mor
$ sudo ./init-eMMC-flasher-v3.sh
208 86319936 Rick Pratt
~~~
209
210
* Change default "debian" user's password.
211
* Verify that password-less root login is now disabled.
212
* Verify that password-less sudo access from debian user is functional
213
214 67985f36 Nitesh Mor
After completing the above hardware setup, go do the steps described in the
215
**Acquire and Compile Required Software** section of the GDP Software Users
216
Guide, and then return to this section to perform the following steps:
217 86319936 Rick Pratt
218
Stop and disable a few default services to free up the web server standard port:
219
220
~~~
221
$ sudo systemctl disable bonescript.service bonescript-autorun.service bonescript.socket
222
$ sudo systemctl stop bonescript.service bonescript-autorun.service bonescript.socket
223
$ sudo systemctl disable cloud9.service cloud9.socket
224
$ sudo systemctl stop cloud9.service cloud9.socket
225
$ sudo systemctl disable node-red.service node-red.socket
226
$ sudo systemctl stop node-red.service node-red.socket
227
$ sudo systemctl disable lighttpd.service
228
$ sudo systemctl stop lighttpd.service
229
~~~
230
231 67985f36 Nitesh Mor
Then proceed to the **Execution and Log Creation** section of the GDP Software
232
Users Guide, being sure to review the **System Administration Tips** section
233
below, after installation is complete.
234 86319936 Rick Pratt
235
**System Administration Tips**
236
237
The BeagleBone Black eMMC will be somewhat tight on working space as configured:
238
239
~~~
240
$ df -h .
241
Filesystem      Size  Used Avail Use% Mounted on
242
/dev/mmcblk1p1  3.5G  3.0G  259M  93% /
243
~~~
244
245 67985f36 Nitesh Mor
Consider adjusting `/etc/logrotate.conf` to rotate "daily" rather than "weekly"
246
or reduce the weekly rotate count from the default 4 to something less, to avoid
247
running out of space when a month's worth of system and daemon logs accumulate.
248
If this was not done at first, space may be consumed by syslog and daemon logs,
249
such that it may be necessary to rotate the syslog and daemon logs followed by
250
deletion to regain space.
251 86319936 Rick Pratt
252 67985f36 Nitesh Mor
Consider pruning the following software directories to gain space, depending
253
upon need:
254 86319936 Rick Pratt
255
~~~
256
$ sudo -i
257
[sudo] password for debian:
258
# pwd
259
/root
260
# df -h /
261
Filesystem      Size  Used Avail Use% Mounted on
262
/dev/mmcblk1p1  3.5G  3.0G  259M  93% /
263
# rm -rf /root/.c9
264
# rm -rf /root/.node-red
265
# rm -rf /opt/cloud9
266
# rm -rf /opt/ti-llvm-3.6
267
# rm -rf /opt/source/adafruit-beaglebone-io-python
268
# rm -rf /opt/source/BB*
269
# rm -rf /opt/source/bb*
270
# rm -rf /opt/source/beagle-tester
271
# rm -rf /opt/source/dtb*
272
# rm -rf /opt/source/fb-test-app
273
# rm -rf /opt/source/prufh
274
# rm -rf /opt/source/Userspace-Arduino
275
# df -h /
276
Filesystem      Size  Used Avail Use% Mounted on
277
/dev/mmcblk1p1  3.5G  2.6G  727M  79% /
278
# exit
279
~~~