Skip to content

Commit 1900e5f

Browse files
author
Catalin Ioana
authored
BLE Mesh initial documentation
Ble mesh initial documentation
2 parents 4996da1 + 4f90055 commit 1900e5f

File tree

3 files changed

+325
-0
lines changed

3 files changed

+325
-0
lines changed

‎config.toml

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -380,6 +380,13 @@ theme = "doc-theme"
380380
parent = "tutorials@all"
381381
weight = 30
382382

383+
[[menu.main]]
384+
name = "BLE Mesh"
385+
url = "/tutorials/all/ble_mesh/"
386+
identifier = "tutorials@all@ble_mesh"
387+
parent = "tutorials@all"
388+
weight = 35
389+
383390
[[menu.main]]
384391
name = "HTTPS"
385392
url = "/tutorials/all/https/"
@@ -821,6 +828,13 @@ theme = "doc-theme"
821828
parent = "firmwareapi@pycom@network@bluetooth"
822829
weight = 60
823830

831+
[[menu.main]]
832+
name = "BLE Mesh"
833+
url = "/firmwareapi/pycom/network/bluetooth/BLE_Mesh/"
834+
identifier = "firmwareapi@pycom@network@bluetooth@BLE_Mesh"
835+
parent = "firmwareapi@pycom@network@bluetooth"
836+
weight = 70
837+
824838
# [Errno 2] No such file or directory: './content/firmwareapi/pycom/network/lora/README.md'
825839
[[menu.main]]
826840
name = "LoRa"

‎content/firmwareapi/pycom/network/bluetooth/BLE_Mesh.md

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
---
2+
title: "BLE_Mesh"
3+
aliases:
4+
- firmwareapi/pycom/network/bluetooth/BLE_Mesh.html
5+
- firmwareapi/pycom/network/bluetooth/BLE_Mesh.md
6+
---
7+
8+
The BLE_Mesh library provides support for connecting to a BLE Mesh Network with various Server and Client models. Currently, Node cannot be configured as Provisioner.
9+
The library is under development, its current limitations:
10+
11+
- Only one Element (primary) can be added to the Node.
12+
- Supported Models:
13+
* Configuration Server Model (automatically generated together with primary Element)
14+
* Generic OnOff Server Model
15+
* Generic OnOff Client Model
16+
* Generic Level Server Model
17+
* Generic Level Client Model
18+
* Sensor Server Model
19+
* Sensor Client Model
20+
21+
- Supported OOB authentication types:
22+
* No OOB
23+
* Output OOB
24+
25+
- Supported Node Features:
26+
* GATT Proxy
27+
* Relay
28+
29+
- Recommended Mobile Applications:
30+
* nRF Mesh (iOS and Android)
31+
* Silicon Labs Bluetoth Mesh (iOS)
32+
* ST BLE Mesh (Android)
33+
* EspBLEMesh (Android)
34+
35+
36+
## Methods of BLE_Mesh class
37+
38+
#### BLE_Mesh.init(name="PYCOM-ESP-BLE-MESH", *, auth=0, callback=None)
39+
40+
Initializes the BLE Mesh module with the pre-configured Elements and Models.
41+
42+
* `name` is the name which will be used to identify the device during Provisioning
43+
* `auth` is the Out-Of-Band (OOB) method. Currently `BLE_Mesh.OOB_OUTPUT` is supported. Without specifying this argument, `NO_OOB` will be used during provisioning.
44+
* `callback` is the callback to be registered. It must have the following arguments:
45+
* `event` returns current event of provisioning.
46+
* `oob_pass` returns the generated pass in case of `BLE_Mesh.OOB_OUTPUT`.
47+
48+
#### BLE_Mesh.set_node_prov(bearer=BLE_Mesh.PROV_NONE, *)
49+
50+
Enable provisioning bearers to get the device ready for provisioning. If OOB is enabled, the callback is used to inform the user about OOB information.
51+
52+
* `bearer` is the transport data protocol between endpoints, can be `BLE_Mesh.PROV_ADV` and/or `BLE_Mesh.PROV_GATT`.
53+
54+
#### BLE_Mesh.reset_node_prov()
55+
56+
Resets the Node Provisioning information.
57+
58+
#### BLE_Mesh.create_element(*, primary, feature=0, beacon=true, ttl=7)
59+
60+
This API creates a new BLE_Mesh_Element object. The BLE_Mesh_Element on concept level is equivalent to the Element in the BLE Mesh terminology.
61+
62+
* `primary` shows whether this new Element will act as the Primary Element of the Node. When a Primary Element is created, the corresponding Configuration Server Model is also automatically created. There can only be 1 Primary Element per Node.
63+
* `feature` shows what features to enable on the new Element. It is an ORED combination of `BLE_Mesh.RELAY`, `BLE_Mesh.LOW_POWER`, `BLE_Mesh.GATT_PROXY`, `BLE_Mesh.FRIEND`
64+
* `ttl` is the default Time To Live value of the packets belonging to the new Element
65+
66+
## Methods of BLE_Mesh_Element object
67+
68+
#### BLE_Mesh_Element.add_model(type=BLE_Mesh.GEN_ONOFF, server_client=BLE_Mesh.SERVER, *, callback=None, value=None, sen_min=-100, sen_max=100, sen_res=0.1)
69+
70+
This API creates a new BLE_Mesh_Model object. The BLE_Mesh_Model on concept level is equivalent to the Model in the BLE Mesh terminology.
71+
72+
* `type` is the type of the new Model.
73+
* `server_client` shows whether the new Model will act as a Server or Client.
74+
* `callback` is the user defined callback to call when any event happens on the Model. It accepts 3 parameters: `new_state`, `event`, `op_code`. The `new_state` is the corresponding state of BLE_Mesh_Model, the `event` and the `op_code` are belonging of the BLE Mesh packet received.
75+
* `value` is the initial value represented by the Model.
76+
* `sen_min` is the minimum value of Sensor State in case of Sensor Model.
77+
* `sen_max` is the maximum value of Sensor State in case of Sensor Model.
78+
* `sen_res` is the resolution of Sensor State in case of Sensor Model.
79+
80+
## Methods of BLE_Mesh_Model object
81+
82+
#### BLE_Mesh_Model.get_state(addr=BLE_Mesh.ADDR_ALL_NODES, app_idx=0, state_type=None)
83+
84+
Gets the State of the Sensor Model. If called from Server Model, returnes with State, in case of Client Model, it sends a Get Message, and returns State through the registered callback.
85+
86+
* `addr` is the address of the remote Node to send the update message.
87+
* `app_idx` is the index of one of the registered Application IDs to use when sending out the message.
88+
* `state_type` is the type of Get State.
89+
90+
#### BLE_Mesh_Model.set_state(state, addr=BLE_Mesh.ADDR_ALL_NODES, app_idx=0, state_type=None)
91+
92+
Sets the State of the Sensor Model. If called from Server Model, sets State directly, in case of Client Model, it sends a Set Message, and updates State.
93+
94+
* `state` is the new value to update the current value with.
95+
* `addr` is the address of the remote Node to send the update message.
96+
* `app_idx` is the index of one of the registered Application IDs to use when sending out the message.
97+
* `state_type` is the type of Set State.
98+
99+
#### BLE_Mesh_Model.status_state(addr=BLE_Mesh.ADDR_ALL_NODES, app_idx=0, state_type=None)
100+
101+
Calling this function only makes sense when the BLE_Mesh_Model is a Server Model. It sends a Status message with the State to the Client Model(s).
102+
103+
* `addr` is the address of the remote Node to send the update message.
104+
* `app_idx` is the index of one of the registered Application IDs to use when sending out the message.
105+
* `state_type` is the type of Status State.
106+
107+
## Constants
108+
109+
* Advertisement options: `BLE_Mesh.PROV_ADV`, `BLE_Mesh.PROV_GATT`, `BLE_Mesh.PROV_NONE`
110+
* Features of an Element: `BLE_Mesh.RELAY`, `BLE_Mesh.LOW_POWER`, `BLE_Mesh.GATT_PROXY`, `BLE_Mesh.FRIEND`
111+
* Authentication options: `BLE_Mesh.OOB_INPUT`, `BLE_Mesh.OOB_OUTPUT`
112+
* Constants for Node addresses: `BLE_Mesh.ADDR_ALL_NODES`, `BLE_Mesh.ADDR_PUBLISH`
113+
* Constants for Model - type: `BLE_Mesh.GEN_ONOFF`, `BLE_Mesh.GEN_LEVEL`, `BLE_Mesh.GEN_SENSOR`, `BLE_Mesh.GEN_SENSOR_SETUP`
114+
* Constants for Model - server or client: `BLE_Mesh.SERVER`, `BLE_Mesh.CLIENT`
115+
* Constants for Model - states: `BLE_Mesh.STATE_ONOFF`, `BLE_Mesh.STATE_LEVEL`, `BLE_Mesh.STATE_LEVEL_DELTA`, `BLE_Mesh.STATE_LEVEL_MOVE`, `BLE_Mesh.SEN_DESCRIPTOR`, `BLE_Mesh.SEN`, `BLE_Mesh.SEN_COLUMN`, `BLE_Mesh.SEN_SERIES`, `BLE_Mesh.SEN_SET_CADENCE`, `BLE_Mesh.SEN_SETTINGS`, `BLE_Mesh.SEN_SETTING`
116+
* Constants for Provision Events: `BLE_Mesh.PROV_REGISTER_EVT`, `BLE_Mesh.PROV_ENABLE_EVT`, `BLE_Mesh.PROV_DISABLE_EVT`, `BLE_Mesh.LINK_OPEN_EVT`, `BLE_Mesh.LINK_CLOSE_EVT`, `BLE_Mesh.PROV_COMPLETE_EVT`, `BLE_Mesh.PROV_RESET_EVT`, `BLE_Mesh.PROV_OUTPUT_OOB_REQ_EVT`, `BLE_Mesh.PROV_INPUT_OOB_REQ_EVT`

‎content/tutorials/all/ble_mesh.md

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
---
2+
title: "BLE Mesh"
3+
aliases:
4+
- tutorials/all/ble_mesh.html
5+
- tutorials/all/ble_mesh.md
6+
- chapter/tutorials/all/ble_mesh
7+
---
8+
9+
BLE Mesh module enables many-to-many device connections, based on Bluetooth module.
10+
11+
# Generic OnOff Example
12+
Generic OnOff model is simplest model in BLE Mesh, makes it possible for one device to switch other devices on or off.
13+
## OnOff Server
14+
OnOff Server has one bool State. Server can Get, Set or send Status abour this State to Client(s). In the example below, during Provisioning, `Output OOB` can be selected, LED is yellow in case of Unprovisioned, and green in case of Provisioned state. Changing the State of Server, LED's light is green or red.
15+
```python
16+
from network import Bluetooth
17+
import pycom
18+
import time
19+
20+
def blink_led(n):
21+
for x in range(n):
22+
pycom.rgbled(0xffff00) # yellow on
23+
time.sleep(0.3)
24+
pycom.rgbled(0x000000) # off
25+
time.sleep(0.3)
26+
27+
def server_cb(new_state, event, recv_op):
28+
print("SERVER | State: ", new_state)
29+
30+
# Turn on LED on board based on State
31+
if new_state == True:
32+
pycom.rgbled(0x007f00) # green
33+
else:
34+
pycom.rgbled(0x7f0000) # red
35+
36+
def prov_callback(event, oob_pass):
37+
if(event == BLE_Mesh.PROV_REGISTER_EVT or event == BLE_Mesh.PROV_RESET_EVT):
38+
# Yellow if not Provision yet or Reseted
39+
pycom.rgbled(0x555500)
40+
if(event == BLE_Mesh.PROV_COMPLETE_EVT):
41+
# Green if Provisioned
42+
pycom.rgbled(0x007f00)
43+
if(event == BLE_Mesh.PROV_OUTPUT_OOB_REQ_EVT):
44+
blink_led(oob_pass)
45+
46+
# BLE Mesh module
47+
BLE_Mesh = Bluetooth.BLE_Mesh
48+
49+
# Turn off the heartbeat behavior of the LED
50+
pycom.heartbeat(False)
51+
52+
# Need to turn ON Bluetooth before using BLE Mesh
53+
bluetooth = Bluetooth()
54+
55+
# Create a Primary Element with GATT Proxy feature and add a Server model to the Element
56+
element = BLE_Mesh.create_element(primary=True, feature=BLE_Mesh.GATT_PROXY)
57+
model_server = element.add_model(BLE_Mesh.GEN_ONOFF, BLE_Mesh.SERVER, callback=server_cb)
58+
59+
# Initialize BLE_Mesh
60+
BLE_Mesh.init("Pycom OnOff Server", auth=BLE_Mesh.OOB_OUTPUT, callback=prov_callback)
61+
62+
# Turn on Provisioning Advertisement
63+
BLE_Mesh.set_node_prov(BLE_Mesh.PROV_ADV|BLE_Mesh.PROV_GATT)
64+
```
65+
66+
## OnOff Client
67+
Client can Get or Set State of Server. In case of Get, or Server Status call, Client Gets the Status through the Model's callback.
68+
```python
69+
from network import Bluetooth
70+
import pycom
71+
import time
72+
73+
def client_cb(new_state, event, recv_op):
74+
print("CLIENT | State: ", new_state)
75+
76+
def prov_callback(event, oob_pass):
77+
if(event == BLE_Mesh.PROV_REGISTER_EVT or event == BLE_Mesh.PROV_RESET_EVT):
78+
# Yellow if not Provision yet or Reseted
79+
pycom.rgbled(0x555500)
80+
if(event == BLE_Mesh.PROV_COMPLETE_EVT):
81+
# Green if Provisioned
82+
pycom.rgbled(0x007f00)
83+
84+
# BLE Mesh module
85+
BLE_Mesh = Bluetooth.BLE_Mesh
86+
87+
# Turn off the heartbeat behavior of the LED
88+
pycom.heartbeat(False)
89+
90+
# Need to turn ON Bluetooth before using BLE Mesh
91+
bluetooth = Bluetooth()
92+
93+
# Create a Primary Element with GATT Proxy feature and add a Server model to the Element
94+
element = BLE_Mesh.create_element(primary=True, feature=BLE_Mesh.GATT_PROXY)
95+
model_client = element.add_model(BLE_Mesh.GEN_ONOFF, BLE_Mesh.CLIENT, callback=client_cb)
96+
97+
# Initialize BLE_Mesh
98+
BLE_Mesh.init("Pycom OnOff Client", callback=prov_callback)
99+
100+
# Turn on Provisioning Advertisement
101+
BLE_Mesh.set_node_prov(BLE_Mesh.PROV_ADV|BLE_Mesh.PROV_GATT)
102+
```
103+
# Sensor Example
104+
In case of Sensor Models, State of Server can be modified only by Server itself, Client can only Get the State by calling Client's Get, or by Servers Status call, but cannot modify the Server's State.
105+
## Sensor Server
106+
In this example Server takes a time measurement every 1 seconds, and send a Status message every 5 seconds, after became Provisioned.
107+
```python
108+
from network import Bluetooth
109+
import pycom
110+
import time
111+
from machine import Timer
112+
113+
def read_sensor(alarm):
114+
# In this example sensor reads local seconds
115+
if(device_provisioned):
116+
model_server.set_state(time.localtime()[5])
117+
print("SENSOR | State: ", model_server.get_state())
118+
119+
def status_sensor(alarm):
120+
if (device_provisioned):
121+
model_server.status_state()
122+
123+
def prov_callback(event, oob_pass):
124+
global device_provisioned
125+
if(event == BLE_Mesh.PROV_REGISTER_EVT or event == BLE_Mesh.PROV_RESET_EVT):
126+
# Yellow if not Provision yet or Reseted
127+
pycom.rgbled(0x555500)
128+
device_provisioned = False
129+
if(event == BLE_Mesh.PROV_COMPLETE_EVT):
130+
# Green if Provisioned
131+
pycom.rgbled(0x007f00)
132+
device_provisioned = True
133+
134+
# BLE Mesh module
135+
BLE_Mesh = Bluetooth.BLE_Mesh
136+
137+
# Turn off the heartbeat behavior of the LED
138+
pycom.heartbeat(False)
139+
140+
# Need to turn ON Bluetooth before using BLE Mesh
141+
bluetooth = Bluetooth()
142+
143+
# Create a Primary Element with GATT Proxy feature and add a Server model to the Element
144+
element = BLE_Mesh.create_element(primary=True, feature=BLE_Mesh.GATT_PROXY)
145+
model_server = element.add_model(BLE_Mesh.SENSOR, BLE_Mesh.SERVER, sen_min = 0, sen_max = 59, sen_res = 1)
146+
147+
# Initialize BLE_Mesh
148+
BLE_Mesh.init("Pycom Sensor Server", callback=prov_callback)
149+
150+
# Turn on Provisioning Advertisement
151+
BLE_Mesh.set_node_prov(BLE_Mesh.PROV_ADV|BLE_Mesh.PROV_GATT)
152+
153+
# Sensor takes measurement every 1 second
154+
Timer.Alarm(read_sensor, 1, periodic=True)
155+
156+
# Sensor send status every 5 seconds
157+
Timer.Alarm(status_sensor, 5, periodic=True)
158+
```
159+
160+
## Sensor Client
161+
Sensor Client is looking for measurements, as Server sends Status every 5 seconds. Between these calls, Client can Get message any time.
162+
```python
163+
from network import Bluetooth
164+
import pycom
165+
166+
def client_cb(new_state, event, recv_op):
167+
print("CLIENT | State: ", new_state)
168+
169+
def prov_callback(event, oob_pass):
170+
if(event == BLE_Mesh.PROV_REGISTER_EVT or event == BLE_Mesh.PROV_RESET_EVT):
171+
# Yellow if not Provision yet or Reseted
172+
pycom.rgbled(0x555500)
173+
if(event == BLE_Mesh.PROV_COMPLETE_EVT):
174+
# Green if Provisioned
175+
pycom.rgbled(0x007f00)
176+
177+
# BLE Mesh module
178+
BLE_Mesh = Bluetooth.BLE_Mesh
179+
180+
# Turn off the heartbeat behavior of the LED
181+
pycom.heartbeat(False)
182+
183+
# Need to turn ON Bluetooth before using BLE Mesh
184+
bluetooth = Bluetooth()
185+
186+
# Create a Primary Element with GATT Proxy feature and add a Server model to the Element
187+
element = BLE_Mesh.create_element(primary=True, feature=BLE_Mesh.GATT_PROXY)
188+
model_client = element.add_model(BLE_Mesh.SENSOR, BLE_Mesh.CLIENT, callback=client_cb, sen_min = 0, sen_max = 59, sen_res = 1)
189+
190+
# Initialize BLE_Mesh
191+
BLE_Mesh.init("Pycom Sensor Client", callback=prov_callback)
192+
193+
# Turn on Provisioning Advertisement
194+
BLE_Mesh.set_node_prov(BLE_Mesh.PROV_ADV|BLE_Mesh.PROV_GATT)
195+
```

0 commit comments

Comments
 (0)