0
# Arduino IoT Client
1

2
Arduino IoT Client is the official JavaScript client library for the Arduino IoT Cloud REST API. It provides comprehensive programmatic access to manage Arduino IoT devices, things, properties, and time-series data. The library is auto-generated from OpenAPI specifications and offers both Node.js and browser compatibility with OAuth2 authentication.
3

4
## Package Information
5

6
- **Package Name**: @arduino/arduino-iot-client
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES6+ with Babel)
9
- **Installation**: `npm install @arduino/arduino-iot-client`
10

11
## Core Imports
12

13
```javascript
14
import ArduinoIotClient from '@arduino/arduino-iot-client';
15
```
16

17
For CommonJS:
18

19
```javascript
20
const ArduinoIotClient = require('@arduino/arduino-iot-client');
21
```
22

23
## Basic Usage
24

25
```javascript
26
import ArduinoIotClient from '@arduino/arduino-iot-client';
27

28
// Configure OAuth2 authentication
29
const defaultClient = ArduinoIotClient.ApiClient.instance;
30
const oauth2 = defaultClient.authentications['oauth2'];
31
oauth2.accessToken = 'YOUR_ACCESS_TOKEN';
32

33
// Create API instances
34
const devicesApi = new ArduinoIotClient.DevicesV2Api();
35
const thingsApi = new ArduinoIotClient.ThingsV2Api();
36
const propertiesApi = new ArduinoIotClient.PropertiesV2Api();
37

38
// List all devices
39
try {
40
  const devices = await devicesApi.devicesV2List();
41
  console.log('Devices:', devices);
42
} catch (error) {
43
  console.error('API Error:', error);
44
}
45

46
// Create a new thing
47
const thingData = {
48
  name: "My IoT Thing",
49
  deviceId: "device-uuid-here"
50
};
51
const newThing = await thingsApi.thingsV2Create(thingData);
52
```
53

54
## Architecture
55

56
Arduino IoT Client is built around several key components:
57

58
- **API Client**: Core HTTP client (`ApiClient`) handling OAuth2 authentication and requests
59
- **API Classes**: 16 specialized API classes covering different functional areas
60
- **Data Models**: 123+ model classes representing all data structures and payloads
61
- **Authentication**: OAuth2 bearer token with organization-level access control
62
- **Error Handling**: HTTP status-based error responses with structured error models
63

64
## Capabilities
65

66
### Device Management
67

68
Complete device lifecycle management including creation, configuration, certificate management, and over-the-air updates.
69

70
```javascript { .api }
71
class DevicesV2Api {
72
  devicesV2Create(createDevicesV2Payload: CreateDevicesV2Payload, opts?: any): Promise<ArduinoDevicev2>;
73
  devicesV2List(opts?: any): Promise<ArduinoDevicev2[]>;
74
  devicesV2Show(id: string, opts?: any): Promise<ArduinoDevicev2>;
75
  devicesV2Update(id: string, devicev2: Devicev2, opts?: any): Promise<ArduinoDevicev2>;
76
  devicesV2Delete(id: string, opts?: any): Promise<void>;
77
}
78
```
79

80
[Device Management](./device-management.md)
81

82
### Thing Management
83

84
IoT thing management with property definitions, sketch handling, and device associations.
85

86
```javascript { .api }
87
class ThingsV2Api {
88
  thingsV2Create(thingCreate: ThingCreate, opts?: any): Promise<ArduinoThing>;
89
  thingsV2List(opts?: any): Promise<ArduinoThing[]>;
90
  thingsV2Show(id: string, opts?: any): Promise<ArduinoThing>;
91
  thingsV2Update(id: string, thingUpdate: ThingUpdate, opts?: any): Promise<ArduinoThing>;
92
  thingsV2Delete(id: string, opts?: any): Promise<void>;
93
}
94
```
95

96
[Thing Management](./thing-management.md) - *Includes legacy ThingsV1Api for backward compatibility*
97

98
### Property Management
99

100
Real-time property value management, timeseries data access, and property configuration.
101

102
```javascript { .api }
103
class PropertiesV2Api {
104
  propertiesV2Create(id: string, property: Property, opts?: any): Promise<ArduinoProperty>;
105
  propertiesV2List(id: string, opts?: any): Promise<ArduinoProperty[]>;
106
  propertiesV2Publish(id: string, pid: string, propertyValue: PropertyValue, opts?: any): Promise<void>;
107
  propertiesV2Timeseries(id: string, pid: string, opts?: any): Promise<ArduinoSeriesResponse>;
108
}
109
```
110

111
[Property Management](./property-management.md) - *Includes legacy PropertiesV1Api for backward compatibility*
112

113
### Dashboard Management
114

115
Visual dashboard creation, widget management, and sharing capabilities.
116

117
```javascript { .api }
118
class DashboardsV2Api {
119
  dashboardsV2Create(dashboardv2: Dashboardv2, opts?: any): Promise<ArduinoDashboardv2>;
120
  dashboardsV2List(opts?: any): Promise<ArduinoDashboardv2[]>;
121
  dashboardsV2Link(id: string, widgetId: string, widgetlink: Widgetlink, opts?: any): Promise<ArduinoWidgetv2>;
122
  dashboardsV2Share(id: string, dashboardshare: Dashboardshare, opts?: any): Promise<void>;
123
}
124
```
125

126
[Dashboard Management](./dashboard-management.md)
127

128
### Time Series Analytics
129

130
Advanced time series data querying with batch operations, sampling, and historical data analysis.
131

132
```javascript { .api }
133
class SeriesV2Api {
134
  seriesV2BatchQuery(batchQueryRequestsMediaV1: BatchQueryRequestsMediaV1, opts?: any): Promise<ArduinoSeriesResponse>;
135
  seriesV2BatchQueryRaw(batchQueryRawRequestsMediaV1: BatchQueryRawRequestsMediaV1, opts?: any): Promise<ArduinoSeriesRawResponse>;
136
  seriesV2HistoricData(historicDataRequest: HistoricDataRequest, opts?: any): Promise<ArduinoSeriesResponse>;
137
}
138
```
139

140
[Time Series Analytics](./timeseries-analytics.md) - *Includes legacy SeriesV1Api for backward compatibility*
141

142
### Automation & Triggers
143

144
Event-driven automation with triggers, actions, and conditional logic for IoT workflows.
145

146
```javascript { .api }
147
class TriggersV1Api {
148
  triggersV1Create(trigger: Trigger, opts?: any): Promise<ArduinoTrigger>;
149
  actionsV1Create(createAction: CreateAction, opts?: any): Promise<ArduinoAction>;
150
  triggersV1List(opts?: any): Promise<ArduinoTrigger[]>;
151
  actionsV1List(opts?: any): Promise<ArduinoAction[]>;
152
}
153
```
154

155
[Automation & Triggers](./automation-triggers.md)
156

157
### LoRa Device Management
158

159
LoRaWAN device creation and frequency plan management for Low Power Wide Area Network deployments.
160

161
```javascript { .api }
162
class LoraDevicesV1Api {
163
  loraDevicesV1Create(createLoraDevicesV1Payload: CreateLoraDevicesV1Payload, opts?: any): Promise<ArduinoLoradevicev1>;
164
}
165

166
class LoraFreqPlanV1Api {
167
  loraFreqPlanV1List(opts?: any): Promise<ArduinoLorafreqplansv1>;
168
}
169
```
170

171
[LoRa Device Management](./lora-device-management.md)
172

173
### Network Credentials & Templates
174

175
Network credentials management and template-based device/thing creation for standardized deployments.
176

177
```javascript { .api }
178
class NetworkCredentialsV1Api {
179
  networkCredentialsV1Show(type: string, opts?: any): Promise<ArduinoCredentialsv1>;
180
  networkCredentialsV1ShowByDevice(type: string, opts?: any): Promise<ArduinoCredentialsv1[]>;
181
}
182

183
class TemplatesApi {
184
  templatesApply(template: Template, opts?: any): Promise<ArduinoTemplate>;
185
}
186
```
187

188
[Network Credentials & Templates](./network-credentials.md)
189

190
## Authentication
191

192
OAuth2 authentication is required for all API operations:
193

194
```javascript { .api }
195
interface OAuth2Config {
196
  accessToken: string;
197
}
198

199
class ApiClient {
200
  static instance: ApiClient;
201
  authentications: {
202
    oauth2: OAuth2Config;
203
  };
204
}
205
```
206

207
**Obtaining Access Token:**
208

209
```javascript
210
const requestPromise = require('request-promise');
211

212
const tokenOptions = {
213
  method: 'POST',
214
  url: 'https://api2.arduino.cc/iot/v1/clients/token',
215
  headers: { 'content-type': 'application/x-www-form-urlencoded' },
216
  json: true,
217
  form: {
218
    grant_type: 'client_credentials',
219
    client_id: 'YOUR_CLIENT_ID',
220
    client_secret: 'YOUR_CLIENT_SECRET',
221
    audience: 'https://api2.arduino.cc/iot'
222
  }
223
};
224

225
const response = await requestPromise(tokenOptions);
226
const accessToken = response.access_token;
227
```
228

229
## Core Data Models
230

231
```javascript { .api }
232
interface ArduinoDevicev2 {
233
  connectionType?: string;
234
  deviceId?: string;
235
  fqbn?: string;
236
  id?: string;
237
  name?: string;
238
  serial?: string;
239
  type?: string;
240
  userId?: string;
241
  webhookActive?: boolean;
242
  webhookUri?: string;
243
}
244

245
interface ArduinoThing {
246
  createdAt?: Date;
247
  deletedAt?: Date;
248
  deviceId?: string;
249
  href?: string;
250
  id?: string;
251
  name?: string;
252
  properties?: ArduinoProperty[];
253
  sketchId?: string;
254
  timezone?: string;
255
  updatedAt?: Date;
256
  userId?: string;
257
  webhookActive?: boolean;
258
  webhookUri?: string;
259
}
260

261
interface ArduinoProperty {
262
  createdAt?: Date;
263
  href?: string;
264
  id?: string;
265
  lastValue?: any;
266
  linkedToTrigger?: boolean;
267
  maxValue?: number;
268
  minValue?: number;
269
  name?: string;
270
  permission?: PropertyPermission;
271
  persist?: boolean;
272
  tag?: number;
273
  thingId?: string;
274
  type?: PropertyType;
275
  updateParameter?: number;
276
  updateStrategy?: PropertyUpdateStrategy;
277
  updatedAt?: Date;
278
  variableName?: string;
279
}
280
```
281

282
## Error Handling
283

284
All API methods return promises that may reject with structured error objects:
285

286
```javascript { .api }
287
interface Error {
288
  code?: string;
289
  detail?: string;
290
  status?: number;
291
}
292
```
293

294
**Error Handling Example:**
295

296
```javascript
297
try {
298
  const devices = await devicesApi.devicesV2List();
299
} catch (error) {
300
  if (error.status === 401) {
301
    console.error('Authentication failed - check access token');
302
  } else if (error.status === 403) {
303
    console.error('Forbidden - check organization permissions');
304
  } else {
305
    console.error('API Error:', error.detail || error.message);
306
  }
307
}
308
```
309

310
## Organization Support
311

312
Multi-tenant support through organization headers:
313

314
```javascript
315
// Pass organization ID in options for all API calls
316
const opts = {
317
  xOrganization: 'your-organization-id'
318
};
319

320
const devices = await devicesApi.devicesV2List(opts);
321
const things = await thingsApi.thingsV2List(opts);
322
```