Orange_IoT / Mbed OS liveobjects-iotsoftbox-basic

Datavenue Live Objects basic sample using liveobjects-iotsoftbox-mqtt library.

Dependencies:   MQTTPacket

README.md@8:82317399e4ce, 2017-04-04 (annotated)

Committer:
jhamel
Date:
Tue Apr 04 16:17:23 2017 +0200
Revision:
8:82317399e4ce
Parent:
0:92f8cff1cf35 
Use CA from Symantec/VeriSign, and fix TLS issue

Who changed what in which revision?

UserRevisionLine numberNew contents of line
jhamel 0:92f8cff1cf35 1 LiveObjects Iot Device Sample
jhamel 0:92f8cff1cf35 2 ==============================
jhamel 0:92f8cff1cf35 3
jhamel 0:92f8cff1cf35 4 This is the LiveObjects IoT Device sample for mbed OS, running on FRDM-K64F board.
jhamel 0:92f8cff1cf35 5
jhamel 0:92f8cff1cf35 6 The application:
jhamel 0:92f8cff1cf35 7
jhamel 0:92f8cff1cf35 8 1. Connects to network with Ethernet (using DHCP)
jhamel 0:92f8cff1cf35 9 1. Connects to the [Datavenue Live Objects Plaftorm](https://liveobjects.orange-business.com/doc/html/lo_manual.html), using:
jhamel 0:92f8cff1cf35 10 * an optional secure connection (TLS)
jhamel 0:92f8cff1cf35 11 * the LiveObjects mode: [Json+Device](https://liveobjects.orange-business.com/doc/html/lo_manual.html#MQTT_MODE_DEVICE)
jhamel 0:92f8cff1cf35 12 1. Publishs
jhamel 0:92f8cff1cf35 13 * the [current Status/Info](https://liveobjects.orange-business.com/doc/html/lo_manual.html#MQTT_DEV_INFO).
jhamel 0:92f8cff1cf35 14 * the [current Configuration Parameters](https://liveobjects.orange-business.com/doc/html/lo_manual.html#MQTT_DEV_CFG)
jhamel 0:92f8cff1cf35 15 * the [current Resources](https://liveobjects.orange-business.com/doc/html/lo_manual.html#MQTT_DEV_RSC)
jhamel 0:92f8cff1cf35 16 1. Subscribes to LiveObjects topics to receive notifications:
jhamel 0:92f8cff1cf35 17 * Configuration Parameters update request
jhamel 0:92f8cff1cf35 18 * Resource update request
jhamel 0:92f8cff1cf35 19 * Command request
jhamel 0:92f8cff1cf35 20 1. then it waits for an event:
jhamel 0:92f8cff1cf35 21 * either from LiveObjects platform to :
jhamel 0:92f8cff1cf35 22 * Update "Configuration Parameters"
jhamel 0:92f8cff1cf35 23 * Update one "Resource" : message or image
jhamel 0:92f8cff1cf35 24 * Process a "Command" : RESET or LED
jhamel 0:92f8cff1cf35 25 * or from terminal (through a very simple menu by typing only one character) to perform one of followings:
jhamel 0:92f8cff1cf35 26 * p : Publish message ("Status" message built by user application)
jhamel 0:92f8cff1cf35 27 * d : Push "Collected Data"
jhamel 0:92f8cff1cf35 28 * s : Push "Status"
jhamel 0:92f8cff1cf35 29 * c : Push "Configuration Parameters"
jhamel 0:92f8cff1cf35 30 * r : Push "Resources"
jhamel 0:92f8cff1cf35 31 * R : system reset
jhamel 0:92f8cff1cf35 32 * if the connection is lost, restart at step 2
jhamel 0:92f8cff1cf35 33
jhamel 0:92f8cff1cf35 34
jhamel 0:92f8cff1cf35 35 See [Datavenue Live Objects - complete guide]((https://liveobjects.orange-business.com/doc/html/lo_manual.html)
jhamel 0:92f8cff1cf35 36
jhamel 0:92f8cff1cf35 37
jhamel 0:92f8cff1cf35 38 ## Required hardware
jhamel 0:92f8cff1cf35 39
jhamel 0:92f8cff1cf35 40 * [FRDM-K64F](http://developer.mbed.org/platforms/frdm-k64f/) board.
jhamel 0:92f8cff1cf35 41 * 1 micro-USB cable.
jhamel 0:92f8cff1cf35 42 * Ethernet cable and connection to the internet.
jhamel 0:92f8cff1cf35 43
jhamel 0:92f8cff1cf35 44
jhamel 0:92f8cff1cf35 45 ## Required software
jhamel 0:92f8cff1cf35 46
jhamel 0:92f8cff1cf35 47 * [mbed-cli](https://github.com/ARMmbed/mbed-cli) - to build the sample programs.
jhamel 0:92f8cff1cf35 48 To learn how to build mbed OS applications with mbed-cli,
jhamel 0:92f8cff1cf35 49 see [the user guide](https://github.com/ARMmbed/mbed-cli/blob/master/README.md).
jhamel 0:92f8cff1cf35 50 * [GCC ARM Embedded Toolchain](https://launchpad.net/gcc-arm-embedded/): Use [5-2015-q4-major](https://launchpad.net/gcc-arm-embedded/5.0/5-2015-q4-major)
jhamel 0:92f8cff1cf35 51 * [Python 2.7](https://www.python.org/downloads/): use [Python 2.7.12 2016-06-25](https://www.python.org/downloads/release/python-2712/)
jhamel 0:92f8cff1cf35 52 * [Serial port monitor](https://developer.mbed.org/handbook/SerialPC#host-interface-and-terminal-applications).
jhamel 0:92f8cff1cf35 53 * [LiveObjects account](http://m2m.orange.com)
jhamel 0:92f8cff1cf35 54
jhamel 0:92f8cff1cf35 55
jhamel 0:92f8cff1cf35 56 ## Brief install
jhamel 0:92f8cff1cf35 57 ```
jhamel 0:92f8cff1cf35 58
jhamel 0:92f8cff1cf35 59 # Install Python 2.7.12 (for example in C:\Python27)
jhamel 0:92f8cff1cf35 60 # Update your environment variable PATH to add "C:\Python27;C:\Python27\Scripts"
jhamel 0:92f8cff1cf35 61
jhamel 0:92f8cff1cf35 62
jhamel 0:92f8cff1cf35 63 # Install GCC ARM embeded tool chain
jhamel 0:92f8cff1cf35 64
jhamel 0:92f8cff1cf35 65
jhamel 0:92f8cff1cf35 66 # Install mbed-cli
jhamel 0:92f8cff1cf35 67 git clone https://github.com/ARMmbed/mbed-cli
jhamel 0:92f8cff1cf35 68 cd mbed-cli
jhamel 0:92f8cff1cf35 69 python setup.py install
jhamel 0:92f8cff1cf35 70
jhamel 0:92f8cff1cf35 71 mbed config --global GCC_ARM_PATH "C:\Program Files (x86)\GNU Tools ARM Embedded\5.2 2015q4\bin"
jhamel 0:92f8cff1cf35 72
jhamel 0:92f8cff1cf35 73 ```
jhamel 0:92f8cff1cf35 74
jhamel 0:92f8cff1cf35 75 ## Application setup
jhamel 0:92f8cff1cf35 76
jhamel 0:92f8cff1cf35 77 To configure the sample application, please:
jhamel 0:92f8cff1cf35 78
jhamel 0:92f8cff1cf35 79 1. [Setup Ethernet](#ethernet-settings).
jhamel 0:92f8cff1cf35 80 1. [Get the LiveObjects API key](#liveobjects-api-key).
jhamel 0:92f8cff1cf35 81 1. [Create and update the user defintions](#liveobjects-header-file).
jhamel 0:92f8cff1cf35 82
jhamel 0:92f8cff1cf35 83 ### Ethernet settings
jhamel 0:92f8cff1cf35 84
jhamel 0:92f8cff1cf35 85 The sample application only uses an Ethernet connection (with DHCP server).
jhamel 0:92f8cff1cf35 86
jhamel 0:92f8cff1cf35 87 So you need:
jhamel 0:92f8cff1cf35 88
jhamel 0:92f8cff1cf35 89 - An Ethernet cable.
jhamel 0:92f8cff1cf35 90 - An Ethernet connection to the internet.
jhamel 0:92f8cff1cf35 91
jhamel 0:92f8cff1cf35 92
jhamel 0:92f8cff1cf35 93 ### LiveObjects API Key
jhamel 0:92f8cff1cf35 94
jhamel 0:92f8cff1cf35 95
jhamel 0:92f8cff1cf35 96 Visit [IoT Soft Box powered by Datavenue](https://liveobjects.orange-business.com/v2/#/sdk)
jhamel 0:92f8cff1cf35 97
jhamel 0:92f8cff1cf35 98 1. You need to request the creation of a developper account.
jhamel 0:92f8cff1cf35 99 1. Then, with your LiveObjects user identifier, login to the [Live Objects portal](https://liveobjects.orange-business.com/#/login).
jhamel 0:92f8cff1cf35 100 1. Go in 'Configuration - API key' tab, and add a new API key.
jhamel 0:92f8cff1cf35 101 **Don't forget to copy this API key value** in a local and secure place during this operation.
jhamel 0:92f8cff1cf35 102
jhamel 0:92f8cff1cf35 103
jhamel 0:92f8cff1cf35 104 ### LiveObjects header file
jhamel 0:92f8cff1cf35 105
jhamel 0:92f8cff1cf35 106 Copy the template header file **liveobjects_dev_params.h.txt** in the new header file **liveobjects_dev_params.h** if it does not exist.
jhamel 0:92f8cff1cf35 107
jhamel 0:92f8cff1cf35 108 Edit this header file to update some values, in particular the **LiveObjects API key**.
jhamel 0:92f8cff1cf35 109
jhamel 0:92f8cff1cf35 110
jhamel 0:92f8cff1cf35 111 ## Terminal Emulator
jhamel 0:92f8cff1cf35 112
jhamel 0:92f8cff1cf35 113 Visit [Serial port monitor](https://developer.mbed.org/handbook/SerialPC#host-interface-and-terminal-applications).
jhamel 0:92f8cff1cf35 114
jhamel 0:92f8cff1cf35 115 Serial Port settings:
jhamel 0:92f8cff1cf35 116
jhamel 0:92f8cff1cf35 117 * Rate: 9600 baud
jhamel 0:92f8cff1cf35 118 * Data: 8 bits
jhamel 0:92f8cff1cf35 119 * Parity : None
jhamel 0:92f8cff1cf35 120 * Stop : 1 stop bit
jhamel 0:92f8cff1cf35 121 * Flow Ctrl: None
jhamel 0:92f8cff1cf35 122
jhamel 0:92f8cff1cf35 123
jhamel 0:92f8cff1cf35 124 ## Building this sample
jhamel 0:92f8cff1cf35 125
jhamel 0:92f8cff1cf35 126 To build the sample application:
jhamel 0:92f8cff1cf35 127
jhamel 0:92f8cff1cf35 128 1. Clone this repository in a local directory. (Note that the name of this directory will the name of binary file)
jhamel 0:92f8cff1cf35 129 1. Open a command line tool and navigate to the project’s directory.
jhamel 0:92f8cff1cf35 130 1. Execute the `mbed config root .` command
jhamel 0:92f8cff1cf35 131 1. Update all sources using the `mbed update` command. This command installs packages: mbed-os, MQTTPacket, iotsoftbox-mqtt, and jsmn)
jhamel 0:92f8cff1cf35 132 1. [Configure](#application-setup) the client application.
jhamel 0:92f8cff1cf35 133 1. Build the application by selecting the hardware board and build the toolchain using the command `mbed compile -m K64F -t GCC_ARM`. mbed-cli builds a binary file under the project’s `.build` directory.
jhamel 0:92f8cff1cf35 134 1. Plug the Ethernet cable into the board if you are using Ethernet mode.
jhamel 0:92f8cff1cf35 135 1. Plug the micro-USB cable into the **OpenSDA** port. The board is listed as a mass-storage device.
jhamel 0:92f8cff1cf35 136 1. Drag and drop the binary `.build/K64F/GCC_ARM/<local_dir_name>.bin` to the board to flash the application.
jhamel 0:92f8cff1cf35 137 1. The board is automatically programmed with the new binary. A flashing LED on it indicates that it is still working. When the LED stops blinking, the board is ready to work.
jhamel 0:92f8cff1cf35 138 1. Start the terminal emulator on serial port : mbed Serial Port (COM..). See [Terminal emulator](#terminal-emulator).
jhamel 0:92f8cff1cf35 139 1. Press the **RESET** button on the board to run the program.
jhamel 0:92f8cff1cf35 140 1. And continue to the [application control](#application-control) chapter.
jhamel 0:92f8cff1cf35 141
jhamel 0:92f8cff1cf35 142
jhamel 0:92f8cff1cf35 143
jhamel 0:92f8cff1cf35 144 ## Application Control
jhamel 0:92f8cff1cf35 145
jhamel 0:92f8cff1cf35 146 ### Serial Terminal
jhamel 0:92f8cff1cf35 147
jhamel 0:92f8cff1cf35 148 The serial port is used by embedded sample application:
jhamel 0:92f8cff1cf35 149
jhamel 0:92f8cff1cf35 150 * output: to print debug/trace messages.
jhamel 0:92f8cff1cf35 151 * input: to do some very simple operations by typing only one character.
jhamel 0:92f8cff1cf35 152 Type 'h' to display the help menu.
jhamel 0:92f8cff1cf35 153
jhamel 0:92f8cff1cf35 154
jhamel 0:92f8cff1cf35 155 ### Live Objects Portal
jhamel 0:92f8cff1cf35 156
jhamel 0:92f8cff1cf35 157 Using your Live Objects user account, go to [Live Objects Portal](https://liveobjects.orange-business.com/#/login).
jhamel 0:92f8cff1cf35 158
jhamel 0:92f8cff1cf35 159
jhamel 0:92f8cff1cf35 160 ### Live Objects Swagger
jhamel 0:92f8cff1cf35 161
jhamel 0:92f8cff1cf35 162 Go in [Live Objects Swagger User Interface](https://liveobjects.orange-business.com/swagger-ui/index.html).
jhamel 0:92f8cff1cf35 163
jhamel 0:92f8cff1cf35 164