github.com/jingruilea/kubeedge@v1.2.0-beta.0.0.20200410162146-4bb8902b3879/docs/mappers/bluetooth_mapper.md

github.com/jingruilea/kubeedge@v1.2.0-beta.0.0.20200410162146-4bb8902b3879/docs/mappers/bluetooth_mapper.md (about)

1 # Bluetooth Mapper
2
3
4 ## Introduction
5
6 Mapper is an application that is used to connect and control devices. This is an implementation of mapper for
7 bluetooth protocol. The aim is to create an application through which users can easily operate devices using bluetooth protocol for communication to the KubeEdge platform. The user is required to provide the mapper with the information required to control their device through the configuration file. These can be changed at runtime by providing the input through the MQTT broker.
8
9 ## Running the mapper
10
11 1. Please ensure that bluetooth service of your device is ON
12 2. Set 'bluetooth=true' label for the node (This label is a prerequisite for the scheduler to schedule bluetooth_mapper pod on the node)
13
14 ```shell
15 kubectl label nodes <name-of-node> bluetooth=true
16 ```
17
18 3. Build and deploy the mapper by following the steps given below.
19
20 ### Building the bluetooth mapper
21
22 ```shell
23 cd $GOPATH/src/github.com/kubeedge/kubeedge/device/bluetooth_mapper
24 make bluetooth_mapper_image
25 docker tag bluetooth_mapper:v1.0 <your_dockerhub_username>/bluetooth_mapper:v1.0
26 docker push <your_dockerhub_username>/bluetooth_mapper:v1.0
27
28 Note: Before trying to push the docker image to the remote repository please ensure that you have signed into docker from your node, if not please type the followig command to sign in
29 docker login
30 # Please enter your username and password when prompted
31 ```
32
33 ### Deploying bluetooth mapper application
34
35 ```shell
36 cd $GOPATH/src/github.com/kubeedge/kubeedge/device/bluetooth_mapper
37
38 # Please enter the following details in the deployment.yaml :-
39 # 1. Replace <edge_node_name> with the name of your edge node at spec.template.spec.voluems.configMap.name
40 # 2. Replace <your_dockerhub_username> with your dockerhub username at spec.template.spec.containers.image
41
42 kubectl create -f deployment.yaml
43 ```
44
45 ## Modules
46
47 The bluetooth mapper consists of the following five major modules :-
48
49 1. Action Manager
50 2. Scheduler
51 3. Watcher
52 4. Controller
53 5. Data Converter
54
55
56 ### Action Manager
57
58 A bluetooth device can be controlled by setting a specific value in physical register(s) of a device and readings can be acquired by
59 getting the value from specific register(s). We can define an Action as a group of read/write operations on a device. A device may support
60 multiple such actions. The registers are identified by characteristic values which are exposed by the device through entities called characteristic-uuids.
61 Each of these actions should be supplied through config-file to action manager or at runtime through MQTT. The values specified initially through the configuration
62 file can be modified at runtime through MQTT. Given below is a guide to provide input to action manager through the configuration file.
63
64 action-manager:
65 actions: # Multiple actions can be added
66 - name: <name of the action>
67 perform-immediately: <true/false>
68 device-property-name: <property-name defined in the device model>
69 - .......
70 .......
71
72 1. Multiple actions can be added in the action manager module. Each of these actions can either be executed by the action manager of invoked by other modules of
73 the mapper like scheduler and watcher.
74
75 2. Name of each action should be unique, it is using this name that the other modules like the scheduler or watcher can invoke which action to perform.
76
77 3. Perform-immediately field of the action manager tells the action manager whether it is supposed to perform the action immediately or not, if it set to true then the action manger will
78 perform the event once.
79
80 4. Each action is associated with a device-property-name, which is the property-name defined in the device CRD, which in turn contains the implementation details required by the action.
81
82
83
84 ### Scheduler
85
86 Scheduler is a component which can perform an action or a set of actions at regular intervals of time. They will make use of the actions previously defined in the action manager module,
87 it has to be ensured that before the execution of the schedule the action should be defined, otherwise it would lead to an error. The schedule can be configured to run for a specified number of times
88 or run infinitely. The scheduler is an optional module and need not be specified if not required by the user. The user can provide input to the scheduler through configuration file or
89 through MQTT at runtime. The values specified initially by the user through the configuration file can be modified at runtime through MQTT. Given below is a guide to provide input to scheduler
90 through the configuration file.
91
92 scheduler:
93 schedules:
94 - name: <name of schedule>
95 interval: <time in milliseconds>
96 occurrence-limit: <number of times to be executed> # if it is 0, then the event will execute infinitely
97 actions:
98 - <action name>
99 - <action name>
100 - ......
101 ......
102
103 1. Multiple schedules can be defined by the user by providing an array as input though the configuration file.
104
105 2. Name specifies the name of the schedule to be executed, each schedule must have a unique name as it is used as a method of identification by the scheduler.
106
107 3. Interval refers to the time interval at which the schedule is meant to be repeated. The user is expected to provide the input in milliseconds.
108
109 4. Occurrence-limit refers to the number of times the action(s) is supposed to occur. If the user wants the event to run infinitely then it can be set to 0 or the field can be skipped.
110
111 5. Actions refer to the action names which are supposed to be executed in the schedule. The actions will be defined in the same order in which they are mentioned here.
112
113 6. The user is expected to provide the names of the actions to be performed in the schedule, in the same order that they are to be executed.
114
115
116 ### Watcher
117
118 The following are the main responsibilities of the watcher component:
119 a) To scan for bluetooth devices and connect to the correct device once it is Online/In-Range.
120
121 b) Keep a watch on the expected state of the twin-attributes of the device and perform the action(s) to make actual state equal to expected.
122
123 c) To report the actual state of twin attributes back to the cloud.
124
125 The watcher is an optional component and need not be defined or used by the user if not necessary. The input to the watcher can be provided through the configuration file or through
126 mqtt at runtime. The values that are defined through the configuration file can be changed at runtime through MQTT. Given below is a guide to provide input to the watcher through the configuration file.
127
128 watcher:
129 device-twin-attributes :
130 - device-property-name: <name of attribute>
131 - <action name>
132 - <action name>
133 - ......
134 ......
135
136 1. Device-property-name refers to the device twin attribute name that was given when creating the device. It is using this name that the watcher watches for any change in expected state.
137
138 2. Actions refers to a list of action names, these are the names of the actions using which we can convert the actual state to the expected state.
139
140 3. The names of the actions being provided must have been defined using the action manager before the mapper begins execution. Also the action names should be mentioned in the same order in which they have
141 to be executed.
142
143
144 ### Controller
145
146 The controller module is responsible for exposing MQTT APIs to perform CRUD operations on the watcher, scheduler and action manager. The controller is also responsible for starting the other modules like action manager, watcher and scheduler.
147 The controller first connects the MQTT client to the broker (using the mqtt configurations, specified in the configuration file), it then initiates the watcher which will connect to the device (based on the configurations provided in the configuration file) and the
148 watcher runs parallelly, after this it starts the action manger which executes all the actions that have been enabled in it, after which the scheduler is started to run parallelly as well. Given below is a guide to provide input to the
149 controller through the configuration file.
150
151 mqtt:
152 mode: 0 # 0 -internal mqtt broker 1 - external mqtt broker
153 server: tcp://127.0.0.1:1883 # external mqtt broker url.
154 internal-server: tcp://127.0.0.1:1884 # internal mqtt broker url.
155 device-model-name: <device_model_name>
156
157
158 ## Usage
159
160 ### Configuration File
161
162 The user can give the configurations specific to the bluetooth device using configurations provided in the configuration file present at $GOPATH/src/github.com/kubeedge/kubeedge/device/bluetooth_mapper/configuration/config.yaml.
163 The details provided in the configuration file are used by action-manager module, scheduler module, watcher module, the data-converter module and the controller.
164
165 **Example:** Given below is the instructions using which user can create their own configuration file, for their device.
166
167 mqtt:
168 mode: 0 # 0 -internal mqtt broker 1 - external mqtt broker
169 server: tcp://127.0.0.1:1883 # external mqtt broker url.
170 internal-server: tcp://127.0.0.1:1884 # internal mqtt broker url.
171 device-model-name: <device_model_name> #deviceID received while registering device with the cloud
172 action-manager:
173 actions: # Multiple actions can be added
174 - name: <name of the action>
175 perform-immediately: <true/false>
176 device-property-name: <property-name defined in the device model>
177 - .......
178 .......
179 scheduler:
180 schedules:
181 - name: <name of schedule>
182 interval: <time in milliseconds>
183 occurrence-limit: <number of times to be executed> # if it is 0, then the event will execute infinitely
184 actions:
185 - <action name>
186 - <action name>
187 - ......
188 - ......
189 watcher:
190 device-twin-attributes :
191 - device-property-name: <name of attribute>
192 actions: # Multiple actions can be added
193 - <action name>
194 - <action name>
195 - ......
196 - ......
197
198
199 ### Runtime Configuration Modifications
200
201 The configuration of the mapper as well as triggering of the modules of the mapper can be done during runtime. The user can do this by
202 publishing messages on the respective MQTT topics of each module. Please note that we have to use the same MQTT broker that is being used by the mapper
203 i.e. if the mapper is using the internal MQTT broker then the messages have to be published on the internal MQTT broker
204 and if the mapper is using the external MQTT broker then the messages have to be published on the external MQTT broker.
205
206 The following properties can be changed at runtime by publishing messages on MQTT topics of the MQTT broker:
207 - Watcher
208 - Action Manager
209 - Scheduler
210
211
212 #### Watcher
213
214 The user can add or update the watcher properties of the mapper at runtime. It will overwrite the existing watcher configurations (if exists)
215
216 **Topic:** $ke/device/bluetooth-mapper/< deviceID >/watcher/create
217
218 **Message:**
219
220 {
221 "device-twin-attributes": [
222 {
223 "device-property-name": "IOControl",
224 "actions": [ # List of names of actions to be performed (actions should have been defined before watching)
225 "IOConfigurationInitialize",
226 "IODataInitialize",
227 "IOConfiguration",
228 "IOData"
229 ]
230 }
231 ]
232 }
233
234 #### Action Manager
235
236 In the action manager module the user can perform two types of operations at runtime, i.e. :
237 1. The user can add or update the actions to be performed on the bluetooth device.
238 2. The user can delete the actions that were previously defined for the bluetooth device.
239
240 ##### Action Add
241
242 The user can add a set of actions to be performed by the mapper. If an action with the same name as one of the actions in the list exists
243 then it updates the action and if the action does not already exist then it is added to the existing set of actions.
244
245 **Topic:** $ke/device/bluetooth-mapper/< deviceID >/action-manager/create
246
247 **Message:**
248
249 [
250 {
251 "name": "IRTemperatureConfiguration", # name of action
252 "perform-immediately": true, # whether the action is to performed immediately or not
253 "device-property-name": "temperature-enable" #property-name defined in the device model
254 },
255 {
256 "name": "IRTemperatureData",
257 "perform-immediately": true,
258 "device-property-name": "temperature" #property-name defined in the device model
259 }
260 ]
261
262 ##### Action Delete
263
264 The users can delete a set of actions that were previously defined for the device. If the action mentioned in the list does not exist
265 then it returns an error message.
266
267 **Topic:** $ke/device/bluetooth-mapper/< deviceID >/action-manager/delete
268
269 **Message:**
270
271 [
272 {
273 "name": "IRTemperatureConfiguration" #name of action to be deleted
274 },
275 {
276 "name": "IRTemperatureData"
277 },
278 {
279 "name": "IOConfigurationInitialize"
280 },
281 {
282 "name": "IOConfiguration"
283 }
284 ]
285
286
287 #### Scheduler
288
289 In the scheduler module the user can perform two types of operations at runtime, i.e. :
290 1. The user can add or update the schedules to be performed on the bluetooth device.
291 2. The user can delete the schedules that were previously defined for the bluetooth device.
292
293 ##### Schedule Add
294
295 The user can add a set of schedules to be performed by the mapper. If a schedule with the same name as one of the schedules in the list exists
296 then it updates the schedule and if the action does not already exist then it is added to the existing set of schedules.
297
298 **Topic:** $ke/device/bluetooth-mapper/< deviceID >/scheduler/create
299
300 **Message:**
301
302 [
303 {
304 "name": "temperature", # name of schedule
305 "interval": 3000, # frequency of the actions to be executed (in milliseconds)
306 "occurrence-limit": 25, # Maximum number of times the event is to be executed, if not given then it runs infinitely
307 "actions": [ # List of names of actions to be performed (actions should have been defined before execution of schedule)
308 "IRTemperatureConfiguration",
309 "IRTemperatureData"
310 ]
311 }
312 ]
313
314 ##### Schedule Delete
315
316 The users can delete a set of schedules that were previously defined for the device. If the schedule mentioned in the list does not exist
317 then it returns an error message.
318
319 **Topic:** $ke/device/bluetooth-mapper/< deviceID >/scheduler/delete
320
321 **Message:**
322
323 [
324 {
325 "name": "temperature" #name of schedule to be deleted
326 }
327 ]