Skip to content

Commit 5a73bc9

Browse files
tomekmalektomekmalek
committed
Update README.md
1 parent 3ee4ed4 commit 5a73bc9

File tree

1 file changed

+100
-118
lines changed

1 file changed

+100
-118
lines changed

‎README.md‎

Lines changed: 100 additions & 118 deletions
Original file line numberDiff line numberDiff line change
@@ -4,56 +4,57 @@
44
This code wraps all the functions necessary to make your object work with Live Objects.
55

66
You can declare parameters, which you can later update OTA from Live objects. You can also create commands to trigger actions remotely.
7-
Only thing u must do yourself is connecting the board with internet.
7+
Only thing you must do yourself is connecting the board with internet.
88

99
Code uses MQTT connection to exchange data with Live objects under the hood to keep your parameters up to date or execute the commands received without you having to take care of them (apart from writing the code of these commands, of course).
1010

1111
## Compatibility ##
12-
| System | MQTT | MQTTS |
13-
| :--- | :---: | :---: |
14-
| Linux | OK |OK |
15-
| Windows | OK |OK |
16-
| Raspberry Pi | OK |OK |
17-
| ESP8266 | OK | - |
18-
| ESP32 | OK | OK |
19-
20-
## Prerequisites/dependecies ##
21-
This code needs a few libraries to run
12+
| System | Connectivity | MQTT | MQTTS |
13+
|:--------------|-----------------|:----:|:-----:|
14+
| Linux | Delivered by OS | OK | OK |
15+
| Windows | Delivered by OS | OK | OK |
16+
| Raspberry Pi | Delivered by OS | OK | OK |
17+
| ESP8266 | WiFi | OK | - |
18+
| ESP32 | WiFi | OK | OK |
19+
| LoPy (Pycom) | WiFi | OK | - |
20+
| GPy (Pycom) | WiFi, LTE | OK | - |
21+
22+
## Prerequisites / dependecies ##
23+
This code needs a few libraries to run:
2224
- Python needs [paho-mqtt](https://pypi.org/project/paho-mqtt/)
25+
- Python for Windows needs [python-certifi-win32](https://pypi.org/project/python-certifi-win32/)
2326
- uPython needs [umqttsimple, umqttrobust and ssl](https://github.com/micropython/micropython-lib)
2427

2528
## How to use ##
2629

27-
1. Log in to [Live Objects](https://liveobjects.orange-business.com) or request a [trial account](https://liveobjects.orange-business.com/#/request_account) (up to 10 devices for 1 year) if you don't have one.
28-
2. Create an [API key](https://liveobjects.orange-business.com/#/administration/apikeys) for your device. Give it a name, select the *Device access* role and validate. Copy the key.
29-
3. Clone or download the directory from Github.
30-
4. Change **\<APIKEY\>** in sketches to one you generated
31-
5. Run script
30+
1. Log in to [Live Objects](https://liveobjects.orange-business.com) or request a [trial account](https://liveobjects.orange-business.com/#/request_account) (up to 10 devices for 1 year) if you don't have one,
31+
2. Create an [API key](https://liveobjects.orange-business.com/#/administration/apikeys) for your device. Give it a name, select the *Device access* role and validate. Copy the key,
32+
3. Clone or download the directory from Github,
33+
4. Change **\<APIKEY\>** in `credentials.py` to one you generated,
34+
5. Run selected `.py` script
3235

3336
## Developer guide ##
3437

3538
### Constructor ###
3639

37-
Constructor of LiveObjects looks like this
40+
Constructor of LiveObjects looks like below:
3841

3942
```Python
40-
lo = LiveObjects.Connection("mqttID",LiveObjects.NONE,"<APIKEY>", debug = True)
43+
lo = LiveObjects.Connection()
4144
```
4245

43-
First parameter is ID of the device, second is type of connection security ( NONE / SSL), third is Api Key to LiveObjects and last is debug mode, if you don't want to output debug messages set it to False. You can also use `lo.setDebug(False)`.
44-
4546
### Debug messages ###
4647

4748
You can use LiveObjects to output debug messages.
4849
```Python
49-
foo = 21
50-
#INFO / ERROR / WARNING
51-
lo.outputDebug(LiveObjects.INFO,"example value", foo, ...)
52-
#Output: [INFO] example value 21 ...
50+
VALUE = 21
51+
# INFO / ERROR / WARNING
52+
lo.outputDebug(LiveObjects.INFO, "example value", VALUE, ...)
53+
# Output: [INFO] example value 21 ...
5354
```
5455

5556
### Declare parameters ###
56-
You can update over the air some parameters of your sketch using Live Objects's parameters. Parameters and Commands must be declared **before** your device connects to Live Objects.
57+
You can update over the air some parameters of your script using Live Objects's parameters. Parameters and Commands must be declared **before** your device connects to Live Objects.
5758

5859
You can declare parameters with the `addParameter()` instruction, which accepts the following arguments:
5960
- the label of your parameter as it will be displayed on Live Objects;
@@ -66,24 +67,24 @@ To retrieve a parameter use function `getParameter()` which takes following argu
6667

6768
Example:
6869
```Python
69-
lo.addParameter("messageRate", 25, LiveObjects.INT);
70-
lo.addParameter("sendDHTData", true ,LiveObjects.BINARY, myCallbackFunction);
71-
...
70+
lo.addParameter("messageRate", 25, LiveObjects.INT)
71+
lo.addParameter("sendDHTData", true, LiveObjects.BINARY, myCallbackFunction)
72+
# ...
7273
if lo.getParameter("sendDHTData"):
73-
lo.addToPayload("temperature",DHT.readTemeprature())
74-
lo.addToPayload("humidity",DHT.readHumidity())
74+
lo.addToPayload("temperature", DHT.readTemeprature())
75+
lo.addToPayload("humidity", DHT.readHumidity())
7576
```
7677

77-
The callback function takes 2 arguments
78+
The callback function takes 2 arguments:
7879
```Python
7980
def myCallbackFunction(parameterName, newValue):
80-
// do stuff
81+
# do stuff
8182
```
8283

8384
Further reading on Live Objects' [Parameters](https://liveobjects.orange-business.com/doc/html/lo_manual.html#_configuration).
8485

8586
### Declare commands ###
86-
Commands lets you trigger specific actions on your device from Live Objects. Parameters and Commands must be declared _before_ your device connects to Live Objects.
87+
Commands let you trigger specific actions on your device from Live Objects. Parameters and Commands must be declared _before_ your device connects to Live Objects.
8788

8889
Commands can be declared using the `addcommand()` instruction, which accepts the following arguments:
8990
- the label of your command
@@ -92,153 +93,134 @@ Commands can be declared using the `addcommand()` instruction, which accepts the
9293
lo.addParameter("a command", myCallback);
9394
```
9495

95-
The callback function should take 1 parameter and return dictonary
96+
The callback function should take 1 parameter and return dictionary:
9697
```Python
9798
def myCallback(args={}):
98-
// do stuff
99-
return {}
99+
# do stuff
100+
return {}
100101
```
101102

102103
Arguments and response are optional when using commands, but they can be useful if you want to pass parameters to your function. For instance, you could define a `play tone` command that will use some parameters like the frequency of the tone, or its duration.
103-
- Any incoming arguments will be passed as member of a dictonary
104-
- You can pass response arguments in the form of a dictonary by returning them
104+
- Any incoming arguments will be passed as member of a dictionary
105+
- You can pass response arguments in the form of a dictionary by returning them
105106
```Python
106107
def playTone(args={}):
107-
duration = args["duration"]
108-
frequency = args["frequency"]
109-
// play the tone accordingly to arguments
110-
...
111-
return {"I played":"the tone"}
112-
}
108+
duration = args["duration"]
109+
frequency = args["frequency"]
110+
# play the tone accordingly to arguments
111+
# ...
112+
return {"I played": "the tone"}
113113

114114
def setup():
115-
lo.addCommand("play tone", playTone)
115+
lo.addCommand("play tone", playTone)
116116
```
117-
> :warning: **Command name and arguments are case-sensitive when creating the command on Live Objects.**: On the opposite, there is no specific order for specifying the command arguments.
117+
> Warning: **Command name and arguments are case-sensitive when creating the command on Live Objects.**: On the opposite, there is no specific order for specifying the command arguments.
118118
119119
Further reading on Live Objects' [Commands](https://liveobjects.orange-business.com/doc/html/lo_manual.html#MQTT_DEV_CMD).
120120

121121
### Sending data ###
122122
You can send data very easily to Live Objects.
123123

124124
#### Dead simple method ####
125-
Compose your payload using the `addToPayload()` instruction. You will need to provide a label for your value, and the data itself. You data can be of any simple type.
125+
Compose your payload using the `addToPayload()` instruction. You will need to provide a label for your value, and the data itself. Your data can be of any simple type.
126126

127127
Data is added on each call to `addToPayload()`, so repeat the instruction if you have multiple data to send. When your payload is ready, send it using `sendData()`. That simple.
128128
```Python
129-
value=21
130-
myOtherValue=37
129+
VALUE = 21
130+
MY_OTHER_VALUE = 37
131131

132132
def foo():
133-
// collect data
134-
lo.addToPayload("my data", value)
135-
lo.addToPayload("my other data", myOtherValue)
136-
lo.sendData() # send to LiveObjects
133+
# collect data
134+
lo.addToPayload("my data", VALUE)
135+
lo.addToPayload("my other data", MY_OTHER_VALUE)
136+
lo.sendData() # send to LiveObjects
137137
```
138138

139-
As soon the data is send, your payload is cleared and waiting for the next sending.
139+
As soon the data is sent, your payload is cleared and waiting for the next sending.
140140

141-
### Advanced payload feautres ###
141+
### Advanced payload features ###
142142
```Python
143-
#add "model" property to your message
144-
lo.addModel("exampleName")
143+
# Add "model" property to your message
144+
lo.addModel("exampleName")
145145

146-
#Add "tag" property to your message
147-
lo.addTag("kitchen")
148-
lo.addTags(["humidity","bathroom"])
146+
# Add "tag" property to your message
147+
lo.addTag("kitchen")
148+
lo.addTags(["humidity", "bathroom"])
149149

150-
#Use your object as payload (this function doesn't append current paylod)
151-
obj = ["example":"value", "example2":"value2" ]
152-
lo.setObjectAsPayload(obj)
150+
# Use your object as payload (this function doesn't append current payload)
151+
obj = {"example":"value", "example2":"value2"}
152+
lo.setObjectAsPayload(obj)
153153
```
154154

155155

156156
### Connect, disconnect and loop ###
157157
You can control the connection and disconnection of your device using `connect()` and `disconnect()`.
158158

159159

160-
161160
In order to check for any incoming configuration update or command, you need to keep the `loop()` instruction in your main loop.
162161
```Python
163162
def foo():
164-
lo.connect();
165-
while True:
166-
#Do some stuff
167-
#...
168-
lo.loop(); #Keep this in main loop
169-
lo.disconnect()
163+
lo.connect();
164+
while True:
165+
# Do some stuff
166+
#...
167+
lo.loop(); #Keep this in main loop
168+
lo.disconnect()
170169
```
171170

172171

173172
# Installation guide for uPython #
174-
## Example for ESP8266 ##
175-
## Requirements ##
173+
## Example for ESP32 / ESP8266 ##
174+
### Requirements ###
176175
1. [ampy](https://learn.adafruit.com/micropython-basics-load-files-and-run-code/install-ampy)
177176
2. [umqttsimple, umqttrobust and ssl](https://github.com/micropython/micropython-lib)
178177
3. [PuTTY](https://www.putty.org/) (for Windows)
179178

180-
## Installation steps ##
181-
1. Copy files into device
182-
```
183-
ampy -pCOMXX put umqttrobus.py
184-
ampy -pCOMXX put umqttsimple.py
185-
ampy -pCOMXX put ssl.py
186-
ampy -pCOMXX put LiveObjects //It will copy directory with its content
187-
```
188-
2. Prepare your sketch and save it as main.py then copy file into device
189-
```
190-
ampy -pCOMXX put main.py
191-
```
192-
3. Setup internet connection in boot.py file and upload it into device.
193-
```Python
194-
# This file is executed on every boot (including wake-boot from deepsleep)
195-
#import esp
196-
#esp.osdebug(None)
197-
import uos, machine
198-
#uos.dupterm(None, 1) # disable REPL on UART(0)
199-
import gc
200-
#import webrepl
201-
#webrepl.start()
202-
gc.collect()
203-
204-
205-
#Network connection
206-
import network
207-
sta_if = network.WLAN(network.STA_IF)
208-
if not sta_if.isconnected():
209-
print('connecting to network...')
210-
sta_if.active(True)
211-
sta_if.connect('SSID', 'PASS')
212-
while not sta_if.isconnected():
213-
pass
214-
print('network config:', sta_if.ifconfig())
215-
```
216-
You may want to get content of file first, then use
179+
### Installation steps ###
180+
181+
1. Preparation
182+
183+
Change **\<APIKEY\>** in `credentials.py` to one you generated.\
184+
Change **\<WIFI_SSID\>** and **\<WIFI_PASS\>** suitable to your WiFi.
185+
186+
187+
2. Copy files into device
188+
```Shell
189+
>ampy -pCOMXX put umqttrobust.py
190+
>ampy -pCOMXX put simple.py
191+
>ampy -pCOMXX put LiveObjects // It will copy directory with its content
217192
```
218-
ampy -pCOMXX get boot.py
193+
3. Prepare your script and save it as `main.py` then copy file into device. You can use one of example ones (`1_send_data.py`, ...) renaming it to `main.py`
194+
```Shell
195+
>ampy -pCOMXX put main.py
219196
```
197+
220198
4. Connect to device and check if it's working using PuTTY
221199

222-
Crtl + D soft resets device
223-
200+
Ctrl + D soft resets device
201+
224202
Ctrl + C Stops currently running script
225203

226-
## Summary ##
227-
After all steps content of the device should look like this
228-
```
204+
### Summary ###
205+
After all steps content of the device should look like below:
206+
```Shell
229207
>ampy -pCOMXX ls
230208
/LiveObjects
231209
/boot.py
232210
/main.py
233-
/ssl.py
234211
/umqttrobust.py
235-
/umqttsimple.py
212+
/simple.py
236213

237214
>ampy -pCOMXX ls LiveObjects
238215
/LiveObjects/Connection.py
239216
/LiveObjects/__init__.py
240-
/LiveObjects/certfile.cer
217+
/LiveObjects/hal.py
218+
/LiveObjects/credentials.py
241219
```
242220

221+
## Example for LoPy / GPy ##
222+
223+
You can do the steps as above but better is to use [Pymakr plug-in](https://pycom.io/products/supported-networks/pymakr/) for **Visual Studio Code** or **Atom** delivered by [Pycom](https://pycom.io/). Plug-in supports code development, its upload to board and communication with board.
224+
243225
## Troubleshooting ##
244226
If you are getting 'MQTT exception: 5' check your api key

0 commit comments

Comments
 (0)