Embed Size (px)
Citation preview
Prep by: Softhouse Doc resp: Softhouse Date: 150824 Doc. no: 1.0.2 Rev: PA1
MVD/LTH Documentation This documentation describes the System used in LTH “PUSS” course. It is intended for teachers, students and IT administrators of the course. For relation to the document style of the course, see chapter on LTH documentation. For teachers presenting on this course, there should be diagrams and text to use when making presentations. Please report any bugs in documentation or the system to [email protected].
Table of Contents Table of Contents
Overview Diagram Use cases System scope
Frontend Requirements Install Configure
Configure PublishApp Configure ScanApp
Usage and testing Test light bulb connection Test Wiced Sense kit connection Test light bulb to broker Test Wiced Sense kit to broker
Tips Backend
Understanding Broker
Client id Topics Quality of Service
Receiver API Database
System Requirements API and Receiver modules
Install Java Broker Database API and Receiver
Start Broker Database
1/26
Prep by: Softhouse Doc resp: Softhouse Date: 150824 Doc. no: 1.0.2 Rev: PA1
API Receiver
Troubleshooting Whole System
Communication Testing Verification
Broker Database API
Any request Swagger
Receiver Appendix
Frontend code example Communicating with BLE devices
Ultron light bulb Wiced Sense
Example MQTT messages Messages Ultron smart bulb
LTH documentation SRS Software Requirements Specification SVVS Software Verification and Validation Specification SVVI Software Verification and Validation Instructions STLDD Software Top Level Design Document SSD Software Specification Document
Assignment proposal
2/26
Prep by: Softhouse Doc resp: Softhouse Date: 150824 Doc. no: 1.0.2 Rev: PA1
Overview The System for the LTH PUSS course consists of one or more Frontends, each one running on a MVD device, connected to a Backend server running in Linux. The System is used to control and get data from BLE (Bluetooth Low Energy) devices. This is done by calling the Backend API which can get data from the database or send commands to the Frontend. The BLE devices used are a Wiced Sense kit and a Nexturn light bulb. The MVD device used in this system is a regular Android smartphone, with these Frontend requirements.
Diagram
Use cases The functional requirements from a user of the system are to:
1. Turn on/off the light bulb 2. Change color of the light bulb 3. Activate/deactivate that the sensor sends data. 4. Get sensor data for different sensor types (humidity, temperature…) within chosen time
intervals.
System scope The System as delivered and deployed at course start contains only the Frontend and Backend. Any Android app connecting to REST API or Web interface are not included. A specification for developing such an app is found in System specification. No BLE devices are included in delivery of System.
3/26
Prep by: Softhouse Doc resp: Softhouse Date: 150824 Doc. no: 1.0.2 Rev: PA1
Frontend
The frontend consists of two Android apps, ScanApp and PublishApp. The ScanApp scans for devices and handles the communication with the BLE devices. The PublishApp is connected to the Broker via MQTT. It publishes and subscribes on different topics. The ScanApp and the PublishApp communicate with each other by broadcast intents.
Requirements A list of things that are necessary to run the Frontend of the System. Some of the hardware must be procured by the user.
A BLEenabled light bulb of model Ultron saveE LED E27 (not included) A BLEsensor of model Broadcom Wiced (not included) A BLEsupported Android mobile device (not included) of:
Version: Minimum SDK 19, Target SDK 22. ScanApp and PublishApp (from Softhouse) Android SDK tools, like adb (from Google) Documentation (from Softhouse) Command line tool like bash
The BLE sensor and light bulb listed above are the only ones that are verified to work with the MVD system. Other BLE devices will not work in present system. The Android device needs to be BLEenabled, but does not need advanced BLEfunctionality like advertisement capability (“beacon”). For this System, the light bulb and sensor do the advertising. For details of implementations, see Frontend code example. See also Backend Requirements.
4/26
Prep by: Softhouse Doc resp: Softhouse Date: 150824 Doc. no: 1.0.2 Rev: PA1
Install To install the two Frontend apps on an Android device use the tool adb from the Android SDK. Get the apps from the point of delivery and unpack them: $ tar xzvf mvd_frontend_MMDD.tar.gz Connect your android device (see Requirements) $ adb devices ... If you have any previous versions of the app, uninstall these before doing $ cd <FOLDER_WHERE_APPS_ARE_LOCATED> $ adb install PublishApp.apk ... $ adb install ScanApp.apk ... The apps should now be found on the device among other Apps/Programs.
Configure Ensure that the device has Bluetooth set to On and is connected to a WiFi which can access the Broker. Then configure both PublishApp and ScanApp before using them.
Configure PublishApp For PublishApp the address to the running instance of Broker must be set before using it. It is a HOSTNAME, for example vm39.cs.lth.se Ask your system admin for this hostname. Also set a unique client id for connecting to the Broker, by default it is set to ‘ClientID’. Replace it with for example ‘vedstapel’, ‘mussepigg’ or whatever you like as long as it is unique compared to other devices connecting to the same broker. Locate the file configPublishApp.txt on the device. The exact location might differ among devices, here is one example: $ adb shell ls la /mnt/shell/emulated/0/PublishApp/ rwxrwx root sdcard_r 22 20150630 15:40 configPublishApp.txt Get the file $ adb pull /mnt/shell/emulated/0/PublishApp/configPublishApp.txt 3 KB/s (22 bytes in 0.005s) Open the file and change to HOSTNAME. Change ClientId on second line and push the file $ adb push configPublishApp.txt /mnt/shell/emulated/0/PublishApp/ 1 KB/s (22 bytes in 0.013s) Restart the PublishApp. If successful, PublishApp should report your config to the log, e.g. I/PublishApp( PID): connected as 'vedstapel' to broker at HOSTNAME
5/26
Prep by: Softhouse Doc resp: Softhouse Date: 150824 Doc. no: 1.0.2 Rev: PA1
Configure ScanApp For ScanApp you need to specify the Bluetooth addresses of the devices that you want to connect to. First run ScanApp on the connected Android device. Locate the file configScanApp.txt. It is located in a sibling directory to PublishApp but called /ScanApp/. Get the file in the same way as PublishApp’s to your local computer. Open the file, update the addresses (the ones below are just defaults). 90:59:AF:2A:B8:67 00:10:18:01:3E:4C Push the file back to the device. Restart ScanApp. If successful, you should see the configured addresses in the log, e.g. I/ScanApp ( PID): configured to scan for: [90:59:AF:2A:B8:67, 00:10:18:01:3E:4C]
6/26
Prep by: Softhouse Doc resp: Softhouse Date: 150824 Doc. no: 1.0.2 Rev: PA1
Usage and testing Here is how to use and test the Frontend. Make sure apps have been installed and configured. Have the (Ultron) BLE light bulb and (Wiced) BLE sensor ready at hand. Use adb logcat in your terminal (or in a IDE) as a “user interface” to the ScanApp and PublishApp. Here’s a command that catches what’s most relevant: $ adb logcat v time ScanApp:I PublishApp:I *:S That displays output of both apps in one terminal. By splitting the command you can also use two terminals, one for each app.
Test light bulb connection Test connection between light bulb and ScanApp.
1. Connect the light bulb to a power outlet. 2. Run ScanApp. 3. Ensure the log contains
a. A connection between ScanApp and light bulb b. Successful service discovery
Test Wiced Sense kit connection 1. Run ScanApp. 2. Press upper button on Sense kit to start advertising. If connected, it will beep. 3. Verify log contains connecting and service discovery.
Test light bulb to broker 1. Run the PublishApp. 2. Verify in log that PublishApp successfully sends data to Broker.
Test Wiced Sense kit to broker Same, but track the communication from Wiced Sense to Broker.
Tips While developing and testing with Wiced Sense kit we found this to be useful:
Wiced Sense can drain battery quickly remove the battery as soon as it is not used. Keep a coin nearby. Insert battery again when scanning or using sensors.
Mark the Wiced Sense kit with (physical) text label with the last 4 characters, like ...3E:4C so it can be easily identified on your desk.
Keep a stash of extra batteries for the Wiced Sense (CR2032) close at hand. If in doubt, use a battery meter (for button cells) to test Wiced Sense battery. Wiced Sense
can behave irrationally on low power. While it might be possible, we have not attempted to update Wiced Sense firmware or use
its USB connection for device configuration. For the light bulb, a socket with a long cord helps a lot.
7/26
Prep by: Softhouse Doc resp: Softhouse Date: 150824 Doc. no: 1.0.2 Rev: PA1
Procedure for running Wiced Sense Tag on USB Power: 1. Leaving the Battery cover off in this process, press the battery into the battery socket until
you see the RED Led turn on. 2. Run the ScanApp and make sure it connects to the Wiced Sense. 3. Insert USB cable in the tag. 4. Release your finger from the battery, letting the battery drop out of the socket and you are
now running the Tag from the USB Power.
8/26
Prep by: Softhouse Doc resp: Softhouse Date: 150824 Doc. no: 1.0.2 Rev: PA1
Backend The backend consists of 4 modules: a Broker, a Receiver, a Database and a REST API. To make the backend work from scratch, the following steps need to be performed:
1. Understanding 2. System Requirements 3. Install 4. Start 5. Verify
When these steps are done for each module, the backend is ready to use.
Understanding Understanding what each module does makes it easier to install, troubleshoot and run it.
Broker The Broker is implemented as a Mosquitto server, see Installation for more info. To learn more: $ man mosquitto
Client id Clients to the Broker connect using a client id. Client id must be unique so Broker can identify clients. If client is trying to connect to Broker with id that some other already connected client have, Broker won’t allow it to connect and it will throw an exception, stating that it can’t connect to server. Make sure that the PublishApp is correctly configured with a unique name. The Broker uses the MQTT protocol version 3.1.1 MQTT Protocol documentation
Topics Communication between clients through Broker is based on topics. See example MQTT messages. When a client publishes a message it must set a topic on which it is publishing message. All other clients that are subscribed to that topic will receive a message. Devices can send sensor data to the Receiver by publishing on mvd/device/data topic. Devices can also send status update messages to the Receiver by publishing on mvd/device/status topic. API can be used to update status of a device, mvd device will receive message on mvd/device/signal topic from API informing it to update device status and send status message to the Receiver. It is also possible to set sensor value of some devices(ex. color for light bulb) through API. MVD device will receive message on mvd/device/value topic from API, informing it to update specific sensor value of a device (identified by its MAC address).
Quality of Service The Receiver is subscribed to topics with QoS 1 and API uses QoS 1 when it is publishing messages. MVD device should also use QoS 1 when it is publishing messages or subscribing to topics. With QoS set to 1 on both MQTT publisher and subscriber(s), Broker will guarantee that every message will be delivered to subscribers at least once. Broker will store messages in a queue if one or more subscribers are offline, so message can be delivered later when they come online. Broker is configured to store up to 200 messages for offline subscribers. QoS level can be different from client A, who publishes a message, and client B, who receives the published message. Between the sender and the Broker the QoS is defined by the sender. When the Broker sends out the message to all subscribers, the QoS of the subscription from client B is used. If client B has subscribed to the Broker with QoS 1 and client A sends a QoS 2 message, it
9/26
Prep by: Softhouse Doc resp: Softhouse Date: 150824 Doc. no: 1.0.2 Rev: PA1
will be received by client B with QoS 1. And of course it could be delivered more than once to client B, because QoS 1 only guarantees to deliver the message at least once. In this case, if publisher and subscriber have different QoS level, then Broker will use lesser of two QoS to send message to subscriber. If publisher publish on QoS 1 and subscriber is subscribed to QoS 0, then Broker will use QoS 0 to send messages to subscriber and it will not guarantee that messages will be delivered to subscriber. If publisher publish on QoS 0 and subscriber is subscribed to QoS 1 then again Broker will not guarantee that they will be delivered to the subscriber.
Receiver The Receiver module is a Java application that is using Paho Java Client MQTT library to communicate with the Broker.
API The API server serves data to a web client or a mobile app enabling you to read device data or to control the device. The API is developed using Dropwizard framework that packs the executable in a JAR that uses builtin Jetty server to run itself, so it is standalone. The web server will serve pages according to its configuration file. The REST API is described in documentation here. Documentation of the REST API can be found using Swagger.
Database A MySQL database stores device data. To get and operate on the data, use the REST API.
10/26
Prep by: Softhouse Doc resp: Softhouse Date: 150824 Doc. no: 1.0.2 Rev: PA1
System Requirements The software needed to run the Backend consists of software to download from the internet and software shipped by Softhouse. See also Frontend requirements. Needed:
1. Ubuntu 14 Server 2. Java 8 3. MySQL 5.5.43 (Database) 4. Mosquitto MQTT v3.1/v3.1.1 (Broker) 5. API and Receiver modules
The first four are available on the Internet, see Installation. The API and Receiver are provided by Softhouse. Notes:
Other Linux distros might work, but this has not been tested. Ubuntu Server 14.04.2 LTS (GNU/Linux 3.16.030generic x86_64) was used during
development No need for Tomcat since Receiver and API are selfcontained. MySQL database uses InnoDb engine. Alternative database: as long as MariaDb is version 5.5 or higher(up to 10.0.9 because
10.0.9 does not include innoDb by default) it shouldn't be any problems. Most important part is that they are using same MySql connector.
API and Receiver modules For build instructions, see internal file README.md This software is delivered as a compressed TAR file from Softhouse:
mvd_backend_XXXX_YYYYYY.tar.gz Contents: ./CHANGES ./lthmvd/receiver/configuration.yml ./lthmvd/receiver/lthmvdreceiver1.0.jar ./lthmvd/receiver/mvdreceiverservice.sh ./lthmvd/receiver/startReceiver.sh ./lthmvd/receiver/stopReceiver.sh ./lthmvd/database/create_db.sql ./lthmvd/database/create_user.sql ./lthmvd/database/README.md ./lthmvd/broker/mosquitto.conf ./lthmvd/broker/README.md ./lthmvd/api/configuration.yml ./lthmvd/api/lthmvdapi1.0.jar ./lthmvd/api/mvdapiservice.sh ./lthmvd/api/startApi.sh ./lthmvd/api/stopApi.sh
11/26
Prep by: Softhouse Doc resp: Softhouse Date: 150824 Doc. no: 1.0.2 Rev: PA1
Install First make sure a target server (Ubuntu Server) can be made available as a target to install on.
Java Java 8 is needed by several components and not distributed together with Ubuntu 14, so make sure that it is installed. Detailed instructions can be followed here, otherwise just do: $ sudo addaptrepository ppa:webupd8team/java $ sudo aptget update $ sudo aptget install oraclejava8installer Then $ java version should indicate correct version, for example: java version "1.8.0_45" Java(TM) SE Runtime Environment (build 1.8.0_45b14) Java HotSpot(TM) 64Bit Server VM (build 25.45b02, mixed mode)
Broker The Broker used is a Mosquitto MQTT implementation. Install by: $ sudo aptget update $ sudo aptget install mosquitto Broker starts by default on installation. Check that it Is running: $ ps ef | grep mosq should return the PID and the commandline for the Broker process The Mosquitto version can be found like this: $ dpkg l | grep mosquitto mosquitto 0.152ubuntu1 amd64 MQTT version 3.1 compatible message broker Backup the current config file $ sudo cp /etc/mosquitto/mosquitto.conf /etc/mosquitto/mosquitto_orig.conf Stop Broker $ sudo service mosquitto stop Configure Broker by replacing mosquitto.config file. $ sudo cp mosquitto.conf /etc/mosquitto/ Start service $ sudo service mosquitto start Check it is running $ sudo status mosquitto See verification to see how a client can connect to test it.
Database 1. Make sure MySQL is installed, if not do $ sudo aptget install mysqlserver During installation supply a ROOTPASSWORD. When done, you have a (running) MySQL server. 2. Check it is running: $ sudo netstat tap | grep mysql
12/26
Prep by: Softhouse Doc resp: Softhouse Date: 150824 Doc. no: 1.0.2 Rev: PA1
3. Place SQL config files in current folder. $ cp database/*.sql . 4. Start the admin tool: $ mysql u root p and enter ROOTPASSWORD. If successful you should see a prompt. 5. Check version mysql> status 6. Create database First check what databases are available. mysql> SHOW DATABASES; ++ | Database | ++ | information_schema | | mysql | | performance_schema | ++ 3 rows in set (0.00 sec) mysql> source create_db.sql The output should contain “Database changed” and “Query OK...” lines. Ask again what databases are available. It should now also list the database “mvd_university”. 7. Add user Open script create_user.sql and find USERNAME and USERPASSWORD inside. Then check what users already exist in database with command mysql> SELECT User FROM mysql.user; There should be root etc, but no USERNAME. Create user by mysql> source create_user.sql; Check again and user USERNAME should now exist. Try exiting mysql and logging in with USERNAME. If successful, that verifies user account is set correctly. 8. Exit mysql mysql> exit A nice tutorial on CLI use of MySQL.
API and Receiver Open both API and Receiver configuration files and check that the URLs used are suitable to your own network. By default the Database and Broker use host localhost but that can be changed to my.server.com or whatever you like. There is no obvious reason to change the port numbers. See Backend Delivered Software for contents of the supplied TAR file.
1. In a home folder extract compressed TAR file using command: tar zxvf mvd_backend_XXXX_YYYYYY.tar.gz
13/26
Prep by: Softhouse Doc resp: Softhouse Date: 150824 Doc. no: 1.0.2 Rev: PA1
2. Inside lthmvd directory navigate to scripts directory and copy mvdapiservice and mvdreceiverservice scripts to the /etc/init.d/ directory using command: sudo cp script_name /etc/init.d/
3. If you want these services to automatically start API and Receiver at system reboot run following commands: sudo updaterc.d mvdapiservice defaults and sudo updaterc.d mvdreceiverservice defaults
4. If for some reason you don’t want these services to start automatically at reboot anymore run same command as above just with remove parameter(ex. sudo updaterc.d mvdapiservice remove)
14/26
Prep by: Softhouse Doc resp: Softhouse Date: 150824 Doc. no: 1.0.2 Rev: PA1
Start How to start and use each module.
Broker Broker should be automatically started after installation but if for some reason it isn’t or it is stopped then open terminal and run: $ service mosquitto start To check status do: $ service mosquitto status
Database After installation, the Database should normally be running.
API Start/stop/restart and get status of a API by running commands like: $ service mvdapiservice start|stop|restart|status The API process will start and run until closed. Each time a client sends a request to the server it will log to console, like this: 0:0:0:0:0:0:0:1 [16/Jun/2015:09:02:51 +0000] "GET / HTTP/1.1" 404 284 "" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/43.0.2357.81 Safari/537.36" 82 0:0:0:0:0:0:0:1 [16/Jun/2015:09:03:15 +0000] "GET /manufacturer/getManufacturers HTTP/1.1" 500 110 "" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/43.0.2357.81 Safari/537.36" 1631
Receiver Start/stop/restart and get status of a Receiver: $ service mvdreceiverservice start|stop|restart|status Receiver will automatically read configuration parameters from its configuration.yml file.
Troubleshooting 1. Error on start EXCEPTION: MqttException Probable reason: Cannot reach Broker in network. Unreachable? Down? 2. Error on start: Unable to connect to server Probable reason: Cannot connect to database (cannot login?)
15/26
Prep by: Softhouse Doc resp: Softhouse Date: 150824 Doc. no: 1.0.2 Rev: PA1
Whole System The whole system consists of Frontend and Backend. To Frontend BLE devices can connect. TO the Backend clients can connect to the REST API.
Communication The Broker communicates with the API and the PublishApp as well as the PublishApp and Receiver. Each change made in the user app goes via the API and the Broker to the PublishApp. The PublishApp broadcasts the request that is then picked up by the ScanApp that sends the request via BLE to the device. Data flow example:
1. A request received by the API and forwarded to the Broker 2. The Broker sends the request to the PublishApp 3. A broadcast signal is sent by the PublishApp including the request 4. The ScanApp picksup the broadcast and sends it via BLE to the device 5. The device replies to the ScanApp 6. The ScanApp returns the reply to the PublishApp 7. From the PublishApp the reply is sent to the Broker 8. The Broker sends the reply to the Receiver 9. Receiver saves the response in the database
See Backend for more information about its modules.
16/26
Prep by: Softhouse Doc resp: Softhouse Date: 150824 Doc. no: 1.0.2 Rev: PA1
Testing Test of the System as a whole (both Frontend and Backend). Before testing make sure an Ultron smart bulb and a Wiced Sense device is connected to the MVD (See Frontend Manual testing). Also check that the backend is up and running (See Backend Verification). Test Test steps
Turn on Ultron smart bulb.
1. In Swagger press device. 2. Press PUT /device/status. 3. Insert value: "deviceAddress": "<Ultron device address>", "value": "1" 4. Press Try it out! 5. Verify that the smart bulb is on. 6. Press GET /device/id. 7. Verify that the smart bulb has status 1.
Activate Wiced Sense device.
1. In Swagger press device. 2. Press PUT /device/status. 3. Insert value: "deviceAddress": "<Wiced device address>", "value": "1" 4. Press Try it out! 5. Press GET /device/id. 6. Verify that the Wiced Sense has status 1. 7. Press data. 8. Press GET /data/device/id. 9. Verify that there are new sensor data in the database.
Change light color on Ultron smart bulb.
1. In Swagger press device. 2. Press PUT /device/value. 3. Insert value: "deviceAddress": "<Ultron device address>", "value": "00ff0000" 4. Press Try it out! 5. Verify that the light has change to green. 6. Press data. 7. Press GET /data/device/id. 8. Verify that the latest entry is showing color 00ff0000.
Get sensor data for different sensor types.
1. Make sure the Wiced Sense is active(status 1). 2. In Swagger press GET /data/device/sensorType 3. Enter sensor type(accelerometer, gyroscope, magnometer, humidity, pressure, temperature) 4. Press Try it out! 5. Verify that Response Body contains data from the sensor entered.
17/26
Prep by: Softhouse Doc resp: Softhouse Date: 150824 Doc. no: 1.0.2 Rev: PA1
Verification All modules of the Backend should now be installed and started. How can they be verified to work? Before you start make sure all modules are running and necessary ports are open. A very simple verification is to see the status of a running service, see Starting.
Broker If Receiver didn’t throw any errors then Broker is working. Another way to check Broker is through command line: $ netstat tulpen and see if there is a process listening on port 1883 (that is mosquitto broker default port) and check that process program name to see if it is mosquitto.
Database Database service can also be checked with same command. If there is a process with port 3306 then it is probably database (this is MySQL default listening port).
API You can run service command with status parameter(described in Start section) to get a message about api status. Aside from that, there are two additional ways to verify api, but first you must find the HOSTNAME and PORT from the API configuration file.
Any request 1. Make sure API is started 2. Point your browser to http://HOSTNAME:PORT (example: http://localhost:9000/foo.html) 3. In browser you will get a 404 from Jetty server since the page does not exist 4. But on API console you will get an entry like:
0:0:0:0:0:0:0:1 [18/Jun/2015:14:28:22 +0000] "GET /foo.html HTTP/1.1" 404 292 "" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/43.0.2357.81 Safari/537.36" 70 This confirms that the API can answer a request, even if it was not legitimate.
Swagger Verify that the REST API server and the Database can communicate using Swagger. From installation step, get the HOSTNAME and PORT you are using.
1. Point a browser to http://petstore.swagger.io/ 2. In the URL box, change to http://HOSTNAME:PORT/swagger.json
a. Example: http://vm39.cs.lth.se:9000/swagger.json 3. Press: Explore. There should be menu items data and device. 4. Press: data 5. Press: GET /data/devices Get data from all devices 6. Press: Try it out 7. In Response Body, there should be at least one sample device data, represented in JSON.
The Response code should be 200 An alternative to the web browser is to use the command line. Get the exact curl command from the same Swagger page, in this case (all on one line): $ curl X GET header "Accept: application/json" "http://vm39.cs.lth.se:9000/data/devices" would return:
18/26
Prep by: Softhouse Doc resp: Softhouse Date: 150824 Doc. no: 1.0.2 Rev: PA1
["value":"00000000","time":"19910203T04:05:06","sensorType":"color","device":"01:02:03:0A:0B:0C"] It should also be possible to download Swagger and run on the desktop, if network issues prevents access from web.
Receiver To verify if receiver is working, you can use receiver service command with status parameter , as it is described in Start section. Open terminal and type: service mvdreceiverservice status Message will appear, describing current status of a receiver.
19/26
Prep by: Softhouse Doc resp: Softhouse Date: 150824 Doc. no: 1.0.2 Rev: PA1
Appendix
Frontend code example For anyone to get going with connecting to light bulb
Communicating with BLE devices To be able to communicate with BLE devices you need to know which services, characteristics and descriptors the device is using. More information of BLE communication on Android can be found here: https://developer.android.com/guide/topics/connectivity/bluetoothle.html
Ultron light bulb The following service and characteristics controls the light color of the Ultron light bulb. Service: UUID: 0000ffe000001000800000805f9b34fb Characteristic controlling the Red LED: UUID: 0000ffe100001000800000805f9b34fb Values: 0x00 0xff Characteristic controlling the Green LED: UUID: 0000ffe200001000800000805f9b34fb Values: 0x00 0xff Characteristic controlling the Blue LED: UUID: 0000ffe300001000800000805f9b34fb Values: 0x00 0xff Characteristic controlling the White LED: UUID: 0000ffe400001000800000805f9b34fb Values: 0x00 0xff Characteristic controlling all the LEDs: UUID: 0000ffe500001000800000805f9b34fb Values: 0x00000000 0xffffffff
Wiced Sense The following service, characteristic and descriptor is needed to activate sensors on the Wiced sense. Notification service UUID: 739298b687b64984a5dcbdc18b068985 Notification characteristic UUID: 33EF91133B55413EB553FEA1EAADA459 Notification descriptor UUID: 0000290200001000800000805f9b34fb To activate the sensors you need to write to the descriptor above: byte[] ENABLE_NOTIFICATION_VALUE = 0x01, 0x00; You will also need to enable characteristic notification for the given characteristic.
20/26
Prep by: Softhouse Doc resp: Softhouse Date: 150824 Doc. no: 1.0.2 Rev: PA1
When the Wiced sense is active it will send data 10 times per second. Nine of these will contain data from the accelerometer, magnetometer and gyroscope sensor. The last message will contain data from the humidity, temperature and pressure sensor. The formats of the sensor notification message: 1st Notification (19 bytes) | Bit mask | Accelerometer | Gyro Sensor | Magnetometer | | 0x0B | (6 bytes, 2x+2y+2z) | (6 bytes, 2x+2y+2z) | (6 bytes, 2x+2y+2z) | 2nd Notification (7 bytes) | Bit mask | Humidity | Pressure | Temperature | | 0x34 | (2 bytes, percentage) | (2 bytes, mBar*10) | (2 bytes, deg C*10) | Bit mask of sensor data Bit 0: When set, accelerometer included X (2 signed bytes), Y (2 signed bytes) and Z (2 signed bytes). Bit 1: When set, gyro included X (2 signed bytes), Y (2 signed bytes) and Z (2 signed bytes). Bit 2: When set, humidity included (2 unsigned bytes in percentage). Bit 3: When set, magnetometer included X (2 signed bytes), Y (2 signed bytes) and Z (2 signed bytes). Bit 4: When set, pressure included (2 bytes, pressure in mBar * 10) Bit 5: When set, temperature included (2 unsigned bytes, temperature in C * 10).
21/26
Prep by: Softhouse Doc resp: Softhouse Date: 150824 Doc. no: 1.0.2 Rev: PA1
Example MQTT messages Describes the interface between PublishApp (FrontEnd) and Broker (BackEnd). This interface uses MQTT protocol.
Messages Ultron smart bulb
Description MQTT Topic Message Example
Ultron smart bulb connecting to MVD. Initial message sent to broker from PublishApp.
Publish mvd/device/data
"values": [ "color": "00000000" ], "address": "90:59:AF:2A:B8:67", "name": "Nexturn", "time": "20150625T09:22:53"
Publish mvd/device/status
"values": [ "status": 0 ], "address": "90:59:AF:2A:B8:67", "name": "Nexturn", "time": "20150625T09:22:53"
Turn on/off Ultron smart bulb from REST API.
Subscribe mvd/device/signal
"address": "90:59:AF:2A:B8:67", "time": "20150625T09:22:47", "status": 1 or 0
Publish mvd/device/status
"values": [ "status": 1 or 0 ], "address": "90:59:AF:2A:B8:67", "name": "Nexturn",
22/26
Prep by: Softhouse Doc resp: Softhouse Date: 150824 Doc. no: 1.0.2 Rev: PA1
"time": "20150625T09:22:53"
Change light color from REST API.
Subscribe mvd/device/value
"address": "90:59:AF:2A:B8:67", "time": "20150625T09:32:40", "value": "00ff0000"
Publish mvd/device/data
"values": [ "color": "00ff0000" ], "address": "90:59:AF:2A:B8:67", "name": "Nexturn", "time": "20150625T09:32:45"
Messages Wiced sense
Wiced Sense connecting to MVD. Initial message sent to broker from PublishApp.
Publish mvd/device/data
"values": [], "address": "00:10:18:01:4D:0B", "name": "WICED Sense Kit", "time": "20150625T09:41:31"
Publish mvd/device/status
"values": [ "status": 0 ], "address": "00:10:18:01:4D:0B", "name": "WICED Sense Kit", "time": "20150625T09:41:31"
Activate Wiced Sense from REST API.
Subscribe mvd/device/signal
"address": "00:10:18:01:4D:0B",
23/26
Prep by: Softhouse Doc resp: Softhouse Date: 150824 Doc. no: 1.0.2 Rev: PA1
"time": "20150625T09:42:19", "status": 1
Publish mvd/device/status
"values": [ "status": 1 ], "address": "00:10:18:01:4D:0B", "name": "WICED Sense Kit", "time": "20150625T09:42:24"
Publish mvd/device/data
"values": [ "magnometer": "6.7815156;1623;193;1301" , "gyroscope": "1;4;8" , "accelerometer": "0;0;90" ], "address": "00:10:18:01:4D:0B", "name": "WICED Sense Kit", "time": "20150625T09:42:24"
Publish mvd/device/data
"values": [ "pressure": "1016.9" , "temperature": "25.7" , "humidity": "51.8" ], "address": "00:10:18:01:4D:0B", "name": "WICED Sense Kit", "time": "20150625T09:42:25"
24/26
Prep by: Softhouse Doc resp: Softhouse Date: 150824 Doc. no: 1.0.2 Rev: PA1
LTH documentation The LTH course uses a structured form of software documentation with separate documents for each subject. In the document you are reading now, all documentation is in a single document. As a guide to each LTH document it is shown how that information can be found in this single document.
SRS - Software Requirements Specification The Complete system can be used for demonstration purposes. It also acts as a requirement for the System that is to be implemented. The Use cases describe the wanted system at a high level.
SVVS - Software Verification and Validation Specification The System can be tested on a system or subsystem level. Specific BLE devices are needed for all tests except Backend only tests. Special focus should be put on testing the interfaces:
BLE: Device to MVD MQTT: Device to Backend REST: Any client to Backend
SVVI - Software Verification and Validation Instructions There are detailed test instructions for
Test of Frontend only Test of Backend modules Test of MVD (Frontend and Backend)
STLDD - Software Top Level Design Document Read about the overall structure and purpose of the System and its two main parts, Frontend and Backend and how they communicate. Since communication with the Backend is done through MQTT and REST API, rather than through library calls, it was decided to document those API:s rather than the Java code’s API. Javadocs for the Backend is available on request.
SSD - Software Specification Document The System is delivered in its two main parts Frontend and Backend. There are installation instructions for Backend. Version info is found in file CHANGES.
25/26
Prep by: Softhouse Doc resp: Softhouse Date: 150824 Doc. no: 1.0.2 Rev: PA1
Assignment proposal
This describes a proposal for exercises for a student course. The idea is to add Android app (or apps) that can run the use cases of the System. In the overview diagram, the FrontEnd apps give an idea what features are needed:
An app to control light bulb An app to display sensor data
Your job is to implement this functionality so that the Use cases work properly.
Use the description of the complete system to understand how it works and what it should contain.
26/26
