Skip to content

Commit 291d51c

Browse files
pirropirropirropirro
authored
Add connection via device credentials (#521)
* Add Device credentials support * Add device credentials support * Update README * Update verify action * Fix typo * Update node version * Fix lint
1 parent 96ef8cc commit 291d51c

31 files changed

+13317
-5380
lines changed

‎.github/workflows/test.yaml

+1-1
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ jobs:
2222
- name: Integration tests
2323
uses: actions/setup-node@v1
2424
with:
25-
node-version: '12'
25+
node-version: '16'
2626
- run: npm install
2727
- run: npm run lint
2828
- run: npm run test

‎.github/workflows/verify-version.yml

+9-1
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,15 @@ jobs:
4747
name: Verify versions
4848
shell: bash
4949
run: |
50-
if [[ ${{ needs.get-current-version.outputs.version }} > ${{ needs.get-master-version.outputs.version }} ]] ; then
50+
verlte() {
51+
[ "$1" = "`echo -e "$1\n$2" | sort -V | head -n1`" ]
52+
}
53+
54+
verlt() {
55+
[ "$1" = "$2" ] && return 1 || verlte $1 $2
56+
}
57+
58+
if verlt ${{ needs.get-master-version.outputs.version }} ${{ needs.get-current-version.outputs.version }} ; then
5159
echo 'Version is ok!'
5260
else
5361
echo 'Must bump app version' && exit 1

‎.nvmrc

+1-1
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
v14.17.0
1+
v16.15.0

‎LICENSE.txt

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
This file includes licensing information for arduino-iot-js.
22

3-
Copyright (c) 2018
4-
Authors: Fabrizio Mirabito
3+
Copyright (c) 2023
4+
Authors: Fabrizio Mirabito, Francesco Pirrotta
55

66
The software is released under the GNU General Public License, which covers the main body
77
of the [insert app name] code. The terms of this license can be found at:

‎README.md

+74-152
Original file line numberDiff line numberDiff line change
@@ -1,192 +1,114 @@
1-
21
[![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
32
[![npm version](https://badge.fury.io/js/arduino-iot-js.svg)](https://badge.fury.io/js/arduino-iot-js)
43

54
# arduino-iot-js
5+
66
## Introduction
7-
This NPM module provides interaction with the Arduino IoT Cloud MQTT broker. It can be used both from the browser and node.js
87

9-
The main features of this module are:
10-
- Connection/disconnection to Arduino IoT Cloud Broker using WebSocket
11-
- Send IoT Cloud *property* updates
12-
- Listen for IoT Cloud *property* updates made by other clients and/or devices
8+
This library provides interaction with the **Arduino IoT Cloud MQTT broker** and It can be used both from the browser and Node.js
9+
10+
It allows to connect in two different modes:
1311

14-
If you are looking for a way to create, read, update, delete resources like
15-
- Devices
16-
- Things
17-
- Properties
18-
- Data Timeseries
12+
- via **[User credentials](examples/1.user-credentials/README.md)**, to send or listen every properties of a user
13+
- via **[Device credentials](examples/2.device-credentials/README.md)**, to behave as a single device
1914

20-
please check the official [Javascript Rest API client](https://www.npmjs.com/package/@arduino/arduino-iot-client).
15+
The main features of this module are:
2116

22-
If you want to learn more about Arduino IoT Cloud architecture, check the official [getting started documentation](https://www.arduino.cc/en/IoT/HomePage).
17+
- Connection/disconnection to Arduino IoT Cloud Broker using WebSocket
18+
- Behave as a device via MQTT
19+
- Send IoT Cloud _property_ updates
20+
- Listen for IoT Cloud _property_ updates made by other clients and/or devices
2321

22+
If you are looking for a way to create, read, update, delete resources (like Devices , Things, Properties, Data Timeseries, ecc...) please check the official [Javascript Rest API client](https://www.npmjs.com/package/@arduino/arduino-iot-client).
2423

24+
If you want to learn more about Arduino IoT Cloud architecture, check the official [getting started documentation](https://www.arduino.cc/en/IoT/HomePage).
2525

2626
## Installation
2727

28+
Via NPM
29+
2830
```bash
2931
$ npm install arduino-iot-js
3032
```
3133

32-
## How to use
33-
The MQTT connection over Websocket relies on Username / Password authentication. Under the hood, this module uses your user ID (plus a timestamp) as *Username* and needs a valid JWT Token as *Password*. You can use either a valid JWT token or just your API Credentials (*clientId* and *clientSecret*).
34+
Via Yarn
3435

35-
### How to import arduino-iot-js in your project
36-
Using a web application in the browser
37-
```javascript
38-
import { ArduinoIoTCloud } from 'arduino-iot-js'
39-
```
40-
Using nodejs
41-
```javascript
42-
const { ArduinoIoTCloud } = require('arduino-iot-js');
36+
```bash
37+
$ yarn add arduino-iot-js
4338
```
4439

45-
### How to connect to Arduino IoT Cloud broker using API Credentials
46-
```javascript
47-
const { ArduinoIoTCloud } = require('arduino-iot-js');
40+
## How to use
41+
42+
The MQTT connection relies on Username / Password authentication.
4843

49-
const options = {
50-
clientId: "YOUR_CLIENT_ID",
51-
clientSecret: "YOUR_CLIENT_SECRET",
52-
onDisconnect: message => {
53-
console.error(message);
54-
}
55-
}
44+
Under the hood, this module could uses your user ID (plus a timestamp) as _Username_ and a valid JWT Token as _Password_ when needs to connect to every properties (You can use either a valid JWT token or just your API Credentials) or some device credentials.
5645

57-
ArduinoIoTCloud.connect(options)
58-
.then(() => console.log("Connected to Arduino IoT Cloud broker"))
59-
.catch(error => console.error(error));
60-
```
46+
### How to connect via **User Credentials**
6147

62-
### How to listen for property value updates
63-
After a successful connection, you can listen for property updates.
64-
To do this you need:
65-
- The ID of the *Thing* the *property* belongs to. You can list all your things and properties using the [Javascript Rest API client](https://www.npmjs.com/package/@arduino/arduino-iot-client), calling the [GET Things endpoint](https://www.arduino.cc/reference/en/iot/api/index.html#api-ThingsV2-thingsV2List)
66-
- The *variable name* of the property you want to listen
67-
68-
```javascript
69-
const { ArduinoIoTCloud } = require('arduino-iot-js');
70-
const thingId = "THING_ID"
71-
const variableName = "PROPERTY_NAME"
72-
73-
const options = {
74-
clientId: "YOUR_CLIENT_ID",
75-
clientSecret: "YOUR_CLIENT_SECRET",
76-
onDisconnect: message => {
77-
console.error(message);
78-
}
79-
}
48+
- via **API Credentials**
8049

81-
ArduinoIoTCloud.connect(options)
82-
.then(() => {
83-
console.log("Connected to Arduino IoT Cloud broker");
84-
return ArduinoIoTCloud.onPropertyValue(thingId, variableName, showUpdates = value => console.log(value));
85-
})
86-
.then(() => console.log("Callback registered"))
87-
.catch(error => console.log(error));
88-
```
89-
Each time a new value is sent from the Device, the `counterUpdates` callback will be called.
50+
```typescript
51+
import { ArduinoIoTCloud } from 'arduino-iot-js';
9052

91-
### How to disconnect from Arduino IoT Cloud Broker
92-
```javascript
93-
ArduinoCloud.disconnect()
94-
.then(() => console.log("Successfully disconnected"));
95-
```
96-
### How to send property values to the device
97-
To do this you need:
98-
- The ID of the *Thing* the *property* belongs to. You can list all your things and properties using the [Javascript Rest API client](https://www.npmjs.com/package/@arduino/arduino-iot-client), calling the [GET Things endpoint](https://www.arduino.cc/reference/en/iot/api/index.html#api-ThingsV2-thingsV2List)
99-
- The *variable name* of the property you want to set
100-
- Value can be either a string, a boolean or a number
101-
```javascript
102-
const { ArduinoIoTCloud } = require('arduino-iot-js');
103-
const thingId = "THING_ID"
104-
const variableName = "PROPERTY_NAME"
105-
106-
const options = {
107-
clientId: "YOUR_CLIENT_ID",
108-
clientSecret: "YOUR_CLIENT_SECRET",
109-
onDisconnect: message => {
110-
console.error(message);
111-
}
112-
}
53+
(async () => {
54+
const client = await ArduinoIoTCloud.connect({
55+
clientId: 'YOUR_CLIENT_ID',
56+
clientSecret: 'YOUR_CLIENT_SECRET',
57+
onDisconnect: (message) => console.error(message),
58+
});
11359

114-
ArduinoIoTCloud.connect(options).then(() => {
115-
console.log("Connected to Arduino IoT Cloud broker");
116-
ArduinoCloud.sendProperty(thingId, variableName, value).then(() => {
117-
console.log("Property value correctly sent");
118-
});
119-
});
60+
// Send a value to a thing property
61+
const value = 'some value';
62+
client.sendProperty('YOUR_THING_ID', 'YOUR_VARIABLE_NAME', value);
12063

64+
// Listen to a thing property's changes
65+
client.onPropertyValue('YOUR_THING_ID', 'ANOTHER_VARIABLE_NAME', (value) => console.log(value));
66+
})();
12167
```
122-
### How to listen to every user properties updates
123-
```javascript
124-
const { ArduinoIoTCloud } = require('arduino-iot-js');
125-
const ArduinoIoTApi = require('@arduino/arduino-iot-client');
126-
127-
const options = {
128-
clientId: "YOUR_CLIENT_ID",
129-
clientSecret: "YOUR_CLIENT_SECRET",
130-
onDisconnect: message => {
131-
console.error(message);
132-
}
68+
69+
- via **User JWT Token**
70+
71+
```typescript
72+
import { ArduinoIoTCloud } from 'arduino-iot-js';
73+
74+
async function retrieveUserToken() {
75+
// Retrieve JWT Token here
13376
}
13477

135-
// Connect to Arduino IoT Cloud MQTT Broker
136-
ArduinoIoTCloud.connect(options)
137-
.then(() => {
138-
console.log("Connected to Arduino IoT Cloud MQTT broker");
139-
140-
// Init Arduino API Client
141-
const ArduinoIoTClient = ArduinoIoTApi.ApiClient.instance;
142-
ArduinoIoTClient.authentications['oauth2'].accessToken = ArduinoIoTCloud.getToken();
143-
144-
const thingsApi = new ArduinoIoTAPI.ThingsV2Api(ArduinoIoTClient);
145-
const propertiesAPI = new ArduinoIoTApi.PropertiesV2Api(ArduinoIoTClient);
146-
147-
return thingsApi.thingsV2List()
148-
.then(things => {
149-
things.forEach(thing => {
150-
propertiesAPI.propertiesV2List(thing.id)
151-
.then(properties => {
152-
properties.forEach(property => {
153-
ArduinoIoTCloud.onPropertyValue(thing.id, property.variable_name,
154-
showUpdates = value => console.log(property.variable_name + ": " + value))
155-
.then(() => console.log("Callback registered for " + property.variable_name))
156-
.catch(error => console.error(error));
157-
});
158-
})
159-
.catch(error => console.error(error));
160-
});
161-
});
162-
})
163-
.catch(error => console.error(error));
164-
```
78+
(async () => {
79+
const token = await retrieveUserToken();
16580

166-
## Development
81+
const client = await ArduinoIoTCloud.connect({
82+
token,
83+
onDisconnect: (message) => console.error(message),
84+
});
16785

168-
### Testing
169-
In order to test the library you have to export a couple of environment variables and then
170-
launch a specific `npm` script as follows:
86+
// Send a value to a thing property
87+
const value = 'some value';
88+
client.sendProperty('YOUR_THING_ID', 'YOUR_VARIABLE_NAME', value);
17189

172-
```sh
173-
$ export CLIENT_ID=<YOUR_CLIENT_ID>
174-
$ export CLIENT_SECRET=<YOUR_CLIENT_SECRET>
175-
$ npm run test
90+
// Listen to a thing property's changes
91+
client.onPropertyValue('YOUR_THING_ID', 'ANOTHER_VARIABLE_NAME', (value) => console.log(value));
92+
})();
17693
```
17794

178-
## Changelog
179-
### [0.9.0] - 2023-01-16
95+
### How to connect via **Device Credentials**
18096

181-
#### Changed
182-
A few development settings have been updated, this should not affect how the library works.
183-
- 'mqtt' is imported differently if the library is used in the browser or in node.
184-
In browser we're using 'mqtt/dist/mqtt' because of some issues with React with some bundlers (namely, Parcel 2)
185-
186-
See:
97+
```typescript
98+
import { ArduinoIoTCloud } from 'arduino-iot-js';
18799

188-
[https://github.com/mqttjs/MQTT.js/issues/1412#issuecomment-1193363330](https://github.com/mqttjs/MQTT.js/issues/1412#issuecomment-1193363330)
100+
(async () => {
101+
const client = await ArduinoIoTCloud.connect({
102+
deviceId: 'YOUR_DEVICE_ID',
103+
secretKey: 'YOUR_SECRET_KEY',
104+
onDisconnect: (message) => console.error(message),
105+
});
189106

190-
[https://github.com/mqttjs/MQTT.js/issues/1233](https://github.com/mqttjs/MQTT.js/issues/1233)
107+
// Send property's values as a device
108+
const value = 'some value';
109+
client.sendProperty('YOUR_VARIABLE_NAME', value);
191110

192-
- updated README file with this changelog and some instructions about testing
111+
// Listen property's updates
112+
client.onPropertyValue('ANOTHER_VARIABLE_NAME', (value) => console.log(value));
113+
})();
114+
```

‎examples/listenProperties/index.js

-41
This file was deleted.

0 commit comments

Comments
 (0)