0
# Device Management
1

2
Complete device lifecycle management including creation, configuration, certificate management, and over-the-air updates. The Arduino IoT Client provides four specialized API classes for comprehensive device management.
3

4
## Capabilities
5

6
### Core Device Operations
7

8
Primary device management functionality for CRUD operations on IoT devices.
9

10
```javascript { .api }
11
class DevicesV2Api {
12
  /**
13
   * Create a new IoT device
14
   * @param createDevicesV2Payload - Device creation parameters
15
   * @param opts - Optional parameters including organization ID
16
   * @returns Promise<ArduinoDevicev2> - Created device object
17
   */
18
  devicesV2Create(createDevicesV2Payload: CreateDevicesV2Payload, opts?: any): Promise<ArduinoDevicev2>;
19

20
  /**
21
   * List all devices accessible to the authenticated user
22
   * @param opts - Optional parameters including organization ID and pagination
23
   * @returns Promise<ArduinoDevicev2[]> - Array of device objects
24
   */
25
  devicesV2List(opts?: any): Promise<ArduinoDevicev2[]>;
26

27
  /**
28
   * Get detailed information about a specific device
29
   * @param id - Device ID
30
   * @param opts - Optional parameters including organization ID
31
   * @returns Promise<ArduinoDevicev2> - Device object with full details
32
   */
33
  devicesV2Show(id: string, opts?: any): Promise<ArduinoDevicev2>;
34

35
  /**
36
   * Update device configuration and properties
37
   * @param id - Device ID
38
   * @param devicev2 - Updated device configuration
39
   * @param opts - Optional parameters including organization ID
40
   * @returns Promise<ArduinoDevicev2> - Updated device object
41
   */
42
  devicesV2Update(id: string, devicev2: Devicev2, opts?: any): Promise<ArduinoDevicev2>;
43

44
  /**
45
   * Delete a device permanently
46
   * @param id - Device ID
47
   * @param opts - Optional parameters including organization ID
48
   * @returns Promise<void>
49
   */
50
  devicesV2Delete(id: string, opts?: any): Promise<void>;
51

52
  /**
53
   * Get device events and status history
54
   * @param id - Device ID
55
   * @param opts - Optional parameters including date range and organization ID
56
   * @returns Promise<ArduinoDevicev2StatusEvents> - Device events
57
   */
58
  devicesV2GetEvents(id: string, opts?: any): Promise<ArduinoDevicev2StatusEvents>;
59

60
  /**
61
   * Get current device properties and values
62
   * @param id - Device ID
63
   * @param opts - Optional parameters including organization ID
64
   * @returns Promise<ArduinoDevicev2properties[]> - Device properties
65
   */
66
  devicesV2GetProperties(id: string, opts?: any): Promise<ArduinoDevicev2properties[]>;
67

68
  /**
69
   * Get device status events and connection history
70
   * @param id - Device ID
71
   * @param opts - Optional parameters including date range and organization ID
72
   * @returns Promise<ArduinoDevicev2StatusEvents> - Status events
73
   */
74
  devicesV2GetStatusEvents(id: string, opts?: any): Promise<ArduinoDevicev2StatusEvents>;
75

76
  /**
77
   * Get time series data for a specific device property
78
   * @param id - Device ID
79
   * @param pid - Property ID
80
   * @param opts - Optional parameters including time range and organization ID
81
   * @returns Promise<ArduinoSeriesResponse> - Time series data
82
   */
83
  devicesV2Timeseries(id: string, pid: string, opts?: any): Promise<ArduinoSeriesResponse>;
84

85
  /**
86
   * Update device property values in bulk
87
   * @param id - Device ID
88
   * @param propertiesValues - Property values to update
89
   * @param opts - Optional parameters including organization ID
90
   * @returns Promise<void>
91
   */
92
  devicesV2UpdateProperties(id: string, propertiesValues: PropertiesValues, opts?: any): Promise<void>;
93
}
94
```
95

96
**Usage Examples:**
97

98
```javascript
99
import ArduinoIotClient from '@arduino/arduino-iot-client';
100

101
const devicesApi = new ArduinoIotClient.DevicesV2Api();
102

103
// Create a new device
104
const newDevice = await devicesApi.devicesV2Create({
105
  name: "My IoT Sensor",
106
  fqbn: "arduino:samd:nano_33_iot",
107
  type: "mkrwifi1010"
108
});
109

110
// List all devices
111
const allDevices = await devicesApi.devicesV2List();
112
console.log('Total devices:', allDevices.length);
113

114
// Get device details
115
const deviceDetails = await devicesApi.devicesV2Show(newDevice.id);
116
console.log('Device status:', deviceDetails.connectionType);
117

118
// Update device
119
const updatedDevice = await devicesApi.devicesV2Update(newDevice.id, {
120
  name: "Updated Sensor Name",
121
  webhookActive: true,
122
  webhookUri: "https://example.com/webhook"
123
});
124
```
125

126
### Certificate Management
127

128
Device certificate management for secure device authentication and communication.
129

130
```javascript { .api }
131
class DevicesV2CertsApi {
132
  /**
133
   * Create a new certificate for a device
134
   * @param id - Device ID
135
   * @param createDevicesV2CertsPayload - Certificate creation parameters
136
   * @param opts - Optional parameters including organization ID
137
   * @returns Promise<ArduinoDevicev2Cert> - Created certificate
138
   */
139
  devicesV2CertsCreate(id: string, createDevicesV2CertsPayload: CreateDevicesV2CertsPayload, opts?: any): Promise<ArduinoDevicev2Cert>;
140

141
  /**
142
   * List all certificates for a device
143
   * @param id - Device ID
144
   * @param opts - Optional parameters including organization ID
145
   * @returns Promise<ArduinoDevicev2Cert[]> - Array of certificates
146
   */
147
  devicesV2CertsList(id: string, opts?: any): Promise<ArduinoDevicev2Cert[]>;
148

149
  /**
150
   * Get certificate details
151
   * @param id - Device ID
152
   * @param cid - Certificate ID
153
   * @param opts - Optional parameters including organization ID
154
   * @returns Promise<ArduinoDevicev2Cert> - Certificate details
155
   */
156
  devicesV2CertsShow(id: string, cid: string, opts?: any): Promise<ArduinoDevicev2Cert>;
157

158
  /**
159
   * Update certificate configuration
160
   * @param id - Device ID
161
   * @param cid - Certificate ID
162
   * @param devicev2Cert - Updated certificate data
163
   * @param opts - Optional parameters including organization ID
164
   * @returns Promise<ArduinoDevicev2Cert> - Updated certificate
165
   */
166
  devicesV2CertsUpdate(id: string, cid: string, devicev2Cert: Devicev2Cert, opts?: any): Promise<ArduinoDevicev2Cert>;
167

168
  /**
169
   * Delete a device certificate
170
   * @param id - Device ID
171
   * @param cid - Certificate ID
172
   * @param opts - Optional parameters including organization ID
173
   * @returns Promise<void>
174
   */
175
  devicesV2CertsDelete(id: string, cid: string, opts?: any): Promise<void>;
176
}
177
```
178

179
### Over-the-Air Updates (OTA)
180

181
Firmware update management for remote device updates.
182

183
```javascript { .api }
184
class DevicesV2OtaApi {
185
  /**
186
   * Send OTA firmware update via binary URL
187
   * @param id - Device ID
188
   * @param devicev2Otabinaryurl - OTA binary URL configuration
189
   * @param opts - Optional parameters including organization ID
190
   * @returns Promise<void>
191
   */
192
  devicesV2OtaSend(id: string, devicev2Otabinaryurl: Devicev2Otabinaryurl, opts?: any): Promise<void>;
193

194
  /**
195
   * Upload firmware file for OTA update
196
   * @param id - Device ID
197
   * @param otaFile - Firmware file to upload
198
   * @param opts - Optional parameters including organization ID
199
   * @returns Promise<ArduinoDevicev2Otaupload> - Upload response
200
   */
201
  devicesV2OtaUpload(id: string, otaFile: File, opts?: any): Promise<ArduinoDevicev2Otaupload>;
202

203
  /**
204
   * Trigger OTA update using URL payload
205
   * @param id - Device ID
206
   * @param devicev2Otaurlpyalod - OTA URL payload
207
   * @param opts - Optional parameters including organization ID
208
   * @returns Promise<void>
209
   */
210
  devicesV2OtaUrl(id: string, devicev2Otaurlpyalod: Devicev2Otaurlpyalod, opts?: any): Promise<void>;
211
}
212
```
213

214
### Device Authentication
215

216
Device password and authentication management.
217

218
```javascript { .api }
219
class DevicesV2PassApi {
220
  /**
221
   * Set device password for authentication
222
   * @param id - Device ID
223
   * @param devicev2Pass - Password configuration
224
   * @param opts - Optional parameters including organization ID
225
   * @returns Promise<void>
226
   */
227
  devicesV2PassSet(id: string, devicev2Pass: Devicev2Pass, opts?: any): Promise<void>;
228

229
  /**
230
   * Get device password information (not the actual password)
231
   * @param id - Device ID
232
   * @param opts - Optional parameters including organization ID
233
   * @returns Promise<ArduinoDevicev2Pass> - Password info
234
   */
235
  devicesV2PassGet(id: string, opts?: any): Promise<ArduinoDevicev2Pass>;
236

237
  /**
238
   * Verify device password
239
   * @param id - Device ID
240
   * @param checkDevicesV2PassPayload - Password to verify
241
   * @param opts - Optional parameters including organization ID
242
   * @returns Promise<void>
243
   */
244
  devicesV2PassCheck(id: string, checkDevicesV2PassPayload: CheckDevicesV2PassPayload, opts?: any): Promise<void>;
245

246
  /**
247
   * Delete device password
248
   * @param id - Device ID
249
   * @param opts - Optional parameters including organization ID
250
   * @returns Promise<void>
251
   */
252
  devicesV2PassDelete(id: string, opts?: any): Promise<void>;
253
}
254
```
255

256
### Device Tagging
257

258
Device organization and categorization through tags.
259

260
```javascript { .api }
261
class DevicesV2TagsApi {
262
  /**
263
   * Create or update a device tag
264
   * @param id - Device ID
265
   * @param tag - Tag to create or update
266
   * @param opts - Optional parameters including organization ID
267
   * @returns Promise<void>
268
   */
269
  devicesV2TagsUpsert(id: string, tag: Tag, opts?: any): Promise<void>;
270

271
  /**
272
   * List all tags for a device
273
   * @param id - Device ID
274
   * @param opts - Optional parameters including organization ID
275
   * @returns Promise<ArduinoTags> - Device tags
276
   */
277
  devicesV2TagsList(id: string, opts?: any): Promise<ArduinoTags>;
278

279
  /**
280
   * Delete a specific device tag
281
   * @param id - Device ID
282
   * @param key - Tag key to delete
283
   * @param opts - Optional parameters including organization ID
284
   * @returns Promise<void>
285
   */
286
  devicesV2TagsDelete(id: string, key: string, opts?: any): Promise<void>;
287
}
288
```
289

290
## Data Models
291

292
```javascript { .api }
293
interface ArduinoDevicev2 {
294
  connectionType?: string;
295
  createdAt?: Date;
296
  deviceId?: string;
297
  fqbn?: string;
298
  href?: string;
299
  id?: string;
300
  lastActivityAt?: Date;
301
  name?: string;
302
  organizationId?: string;
303
  otaAvailable?: boolean;
304
  otaCompatible?: boolean;
305
  requiredWifiCredentials?: boolean;
306
  serial?: string;
307
  type?: string;
308
  updatedAt?: Date;
309
  userId?: string;
310
  webhookActive?: boolean;
311
  webhookUri?: string;
312
}
313

314
interface CreateDevicesV2Payload {
315
  connectionType?: string;
316
  fqbn?: string;
317
  name?: string;
318
  serial?: string;
319
  softDeleted?: boolean;
320
  type?: string;
321
  userId?: string;
322
  wifiCredentialsId?: string;
323
}
324

325
interface ArduinoDevicev2Cert {
326
  ca?: string;
327
  compressed?: ArduinoCompressedv2;
328
  createdAt?: Date;
329
  deviceId?: string;
330
  enabled?: boolean;
331
  id?: string;
332
  updatedAt?: Date;
333
}
334

335
interface ArduinoCompressedv2 {
336
  ca?: string;
337
  cert?: string;
338
  key?: string;
339
}
340

341
interface ArduinoDevicev2StatusEvents {
342
  events?: ArduinoDevicev2StatusEvent[];
343
}
344

345
interface ArduinoDevicev2StatusEvent {
346
  deviceId?: string;
347
  eventType?: string;
348
  id?: string;
349
  timestamp?: Date;
350
}
351

352
interface ArduinoDevicev2properties {
353
  lastValue?: any;
354
  lastValueUpdatedAt?: Date;
355
  name?: string;
356
  permission?: PropertyPermission;
357
  propertyId?: string;
358
  type?: string;
359
  updateParameter?: number;
360
  updateStrategy?: PropertyUpdateStrategy;
361
  variableName?: string;
362
}
363

364
interface ArduinoDevicev2Pass {
365
  password?: string;
366
}
367

368
interface ArduinoTags {
369
  [key: string]: string;
370
}
371

372
interface Tag {
373
  key: string;
374
  value: string;
375
}
376
```
377

378
**Complete Device Management Example:**
379

380
```javascript
381
import ArduinoIotClient from '@arduino/arduino-iot-client';
382

383
// Initialize APIs
384
const devicesApi = new ArduinoIotClient.DevicesV2Api();
385
const devicesV2CertsApi = new ArduinoIotClient.DevicesV2CertsApi();
386
const devicesV2TagsApi = new ArduinoIotClient.DevicesV2TagsApi();
387
const devicesV2PassApi = new ArduinoIotClient.DevicesV2PassApi();
388

389
// Create and configure a complete device setup
390
async function setupDevice() {
391
  try {
392
    // Create device
393
    const device = await devicesApi.devicesV2Create({
394
      name: "Production Sensor",
395
      fqbn: "arduino:samd:nano_33_iot",
396
      type: "mkrwifi1010",
397
      connectionType: "wifi"
398
    });
399

400
    console.log('Created device:', device.id);
401

402
    // Set device password
403
    await devicesV2PassApi.devicesV2PassSet(device.id, {
404
      password: "secure-device-password"
405
    });
406

407
    // Add tags for organization
408
    await devicesV2TagsApi.devicesV2TagsUpsert(device.id, {
409
      key: "environment",
410
      value: "production"
411
    });
412

413
    await devicesV2TagsApi.devicesV2TagsUpsert(device.id, {
414
      key: "location",
415
      value: "warehouse-a"
416
    });
417

418
    // Create certificate for secure communication
419
    const cert = await devicesV2CertsApi.devicesV2CertsCreate(device.id, {
420
      enabled: true
421
    });
422

423
    console.log('Device setup complete with certificate:', cert.id);
424

425
    return device;
426
  } catch (error) {
427
    console.error('Device setup failed:', error);
428
    throw error;
429
  }
430
}
431
```