0
# Thing Management
1

2
IoT thing management with property definitions, sketch handling, and device associations. Things represent logical entities in your IoT system that can contain multiple properties and be associated with physical devices.
3

4
## Capabilities
5

6
### Core Thing Operations
7

8
Primary thing management functionality for CRUD operations on IoT things.
9

10
```javascript { .api }
11
class ThingsV2Api {
12
  /**
13
   * Create a new IoT thing
14
   * @param thingCreate - Thing creation parameters
15
   * @param opts - Optional parameters including organization ID
16
   * @returns Promise<ArduinoThing> - Created thing object
17
   */
18
  thingsV2Create(thingCreate: ThingCreate, opts?: any): Promise<ArduinoThing>;
19

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

27
  /**
28
   * Get detailed information about a specific thing
29
   * @param id - Thing ID
30
   * @param opts - Optional parameters including organization ID and show_properties flag
31
   * @returns Promise<ArduinoThing> - Thing object with full details
32
   */
33
  thingsV2Show(id: string, opts?: any): Promise<ArduinoThing>;
34

35
  /**
36
   * Update thing configuration and metadata
37
   * @param id - Thing ID
38
   * @param thingUpdate - Updated thing configuration
39
   * @param opts - Optional parameters including organization ID
40
   * @returns Promise<ArduinoThing> - Updated thing object
41
   */
42
  thingsV2Update(id: string, thingUpdate: ThingUpdate, opts?: any): Promise<ArduinoThing>;
43

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

52
  /**
53
   * Clone an existing thing with all its properties
54
   * @param id - Thing ID to clone
55
   * @param thingClone - Clone configuration including new name
56
   * @param opts - Optional parameters including organization ID
57
   * @returns Promise<ArduinoThing> - Cloned thing object
58
   */
59
  thingsV2Clone(id: string, thingClone: ThingClone, opts?: any): Promise<ArduinoThing>;
60

61
  /**
62
   * Get thing as a template for replication
63
   * @param id - Thing ID
64
   * @param opts - Optional parameters including organization ID
65
   * @returns Promise<ArduinoThingtemplate> - Thing template
66
   */
67
  thingsV2Template(id: string, opts?: any): Promise<ArduinoThingtemplate>;
68
}
69
```
70

71
**Usage Examples:**
72

73
```javascript
74
import ArduinoIotClient from '@arduino/arduino-iot-client';
75

76
const thingsApi = new ArduinoIotClient.ThingsV2Api();
77

78
// Create a new thing
79
const newThing = await thingsApi.thingsV2Create({
80
  name: "Smart Home Sensor",
81
  deviceId: "device-uuid-here",
82
  timezone: "America/New_York"
83
});
84

85
// List all things with pagination
86
const things = await thingsApi.thingsV2List({
87
  page: 1,
88
  size: 20,
89
  showProperties: true
90
});
91

92
// Get thing details with properties
93
const thingDetails = await thingsApi.thingsV2Show(newThing.id, {
94
  showProperties: true
95
});
96
console.log('Thing properties:', thingDetails.properties);
97

98
// Clone a thing for testing
99
const clonedThing = await thingsApi.thingsV2Clone(newThing.id, {
100
  name: "Smart Home Sensor - Test",
101
  includeProperties: true
102
});
103
```
104

105
### Arduino Sketch Management
106

107
Manage Arduino sketches associated with things for code deployment and updates.
108

109
```javascript { .api }
110
class ThingsV2Api {
111
  /**
112
   * Create a new Arduino sketch for a thing
113
   * @param id - Thing ID
114
   * @param thingSketch - Sketch creation parameters including code content
115
   * @param opts - Optional parameters including organization ID
116
   * @returns Promise<ArduinoThing> - Updated thing with sketch information
117
   */
118
  thingsV2CreateSketch(id: string, thingSketch: ThingSketch, opts?: any): Promise<ArduinoThing>;
119

120
  /**
121
   * Update an existing Arduino sketch
122
   * @param id - Thing ID
123
   * @param sketchId - Sketch ID
124
   * @param updateSketch - Updated sketch content and metadata
125
   * @param opts - Optional parameters including organization ID
126
   * @returns Promise<ArduinoThing> - Updated thing with sketch information
127
   */
128
  thingsV2UpdateSketch(id: string, sketchId: string, updateSketch: UpdateSketch, opts?: any): Promise<ArduinoThing>;
129

130
  /**
131
   * Delete the Arduino sketch from a thing
132
   * @param id - Thing ID
133
   * @param opts - Optional parameters including organization ID
134
   * @returns Promise<void>
135
   */
136
  thingsV2DeleteSketch(id: string, opts?: any): Promise<void>;
137
}
138
```
139

140
### Thing Tagging
141

142
Thing organization and categorization through tags.
143

144
```javascript { .api }
145
class ThingsV2TagsApi {
146
  /**
147
   * Create or update a thing tag
148
   * @param id - Thing ID
149
   * @param tag - Tag to create or update
150
   * @param opts - Optional parameters including organization ID
151
   * @returns Promise<void>
152
   */
153
  thingsV2TagsUpsert(id: string, tag: Tag, opts?: any): Promise<void>;
154

155
  /**
156
   * List all tags for a thing
157
   * @param id - Thing ID
158
   * @param opts - Optional parameters including organization ID
159
   * @returns Promise<ArduinoTags> - Thing tags
160
   */
161
  thingsV2TagsList(id: string, opts?: any): Promise<ArduinoTags>;
162

163
  /**
164
   * Delete a specific thing tag
165
   * @param id - Thing ID
166
   * @param key - Tag key to delete
167
   * @param opts - Optional parameters including organization ID
168
   * @returns Promise<void>
169
   */
170
  thingsV2TagsDelete(id: string, key: string, opts?: any): Promise<void>;
171
}
172
```
173

174
### Legacy Thing Operations (V1 API)
175

176
Legacy thing management functionality for backward compatibility. Use ThingsV2Api for new integrations.
177

178
```javascript { .api }
179
class ThingsV1Api {
180
  /**
181
   * Create a new thing associated to the user (legacy)
182
   * @param createThingsV1Payload - Thing creation payload
183
   * @param opts - Optional parameters including force flag to detach device from other things
184
   * @returns Promise<ArduinoThing> - Created thing object
185
   */
186
  thingsV1Create(createThingsV1Payload: CreateThingsV1Payload, opts?: any): Promise<ArduinoThing>;
187

188
  /**
189
   * List all things associated to the user (legacy)
190
   * @param opts - Optional parameters including acrossUserIds, deviceId, and showDeleted flags
191
   * @returns Promise<ArduinoThing[]> - Array of thing objects
192
   */
193
  thingsV1List(opts?: any): Promise<ArduinoThing[]>;
194

195
  /**
196
   * Get thing details (legacy)
197
   * @param id - Thing ID
198
   * @param opts - Optional parameters including showDeleted flag
199
   * @returns Promise<ArduinoThing> - Thing object with full details
200
   */
201
  thingsV1Show(id: string, opts?: any): Promise<ArduinoThing>;
202

203
  /**
204
   * Update thing configuration (legacy)
205
   * @param id - Thing ID
206
   * @param thing - Updated thing payload
207
   * @param opts - Optional parameters including force flag
208
   * @returns Promise<ArduinoThing> - Updated thing object
209
   */
210
  thingsV1Update(id: string, thing: Thing, opts?: any): Promise<ArduinoThing>;
211

212
  /**
213
   * Delete a thing (legacy)
214
   * @param id - Thing ID
215
   * @param opts - Optional parameters including force flag for hard delete
216
   * @returns Promise<void>
217
   */
218
  thingsV1Delete(id: string, opts?: any): Promise<void>;
219

220
  /**
221
   * Create sketch for thing (legacy)
222
   * @param id - Thing ID
223
   * @param thingSketch - Sketch configuration payload
224
   * @returns Promise<ArduinoThing> - Thing object with sketch information
225
   */
226
  thingsV1CreateSketch(id: string, thingSketch: ThingSketch, opts?: any): Promise<ArduinoThing>;
227

228
  /**
229
   * Update existing thing sketch (legacy)
230
   * @param id - Thing ID
231
   * @param sketchId - Sketch ID
232
   * @returns Promise<ArduinoThing> - Updated thing object
233
   */
234
  thingsV1UpdateSketch(id: string, sketchId: string, opts?: any): Promise<ArduinoThing>;
235

236
  /**
237
   * Delete thing sketch (legacy)
238
   * @param id - Thing ID
239
   * @returns Promise<ArduinoThing> - Thing object without sketch
240
   */
241
  thingsV1DeleteSketch(id: string, opts?: any): Promise<ArduinoThing>;
242

243
  /**
244
   * Get thing layout without last values data (legacy)
245
   * @param id - Thing ID
246
   * @param opts - Optional parameters including showDeleted flag
247
   * @returns Promise<ArduinoThinglayout> - Thing layout information
248
   */
249
  thingsV1Layout(id: string, opts?: any): Promise<ArduinoThinglayout>;
250
}
251
```
252

253
**Migration Note:** V1 API has different payload structures and behavior compared to V2. V2 provides improved validation, better error handling, enhanced filtering options, and more consistent API patterns.
254

255
## Data Models
256

257
```javascript { .api }
258
interface ArduinoThing {
259
  createdAt?: Date;
260
  deletedAt?: Date;
261
  deviceId?: string;
262
  href?: string;
263
  id?: string;
264
  name?: string;
265
  organizationId?: string;
266
  properties?: ArduinoProperty[];
267
  propertiesCount?: number;
268
  sketchId?: string;
269
  timezone?: string;
270
  updatedAt?: Date;
271
  userId?: string;
272
  webhookActive?: boolean;
273
  webhookUri?: string;
274
}
275

276
interface ThingCreate {
277
  assistantId?: string;
278
  deviceId?: string;
279
  id?: string;
280
  name: string;
281
  properties?: ArduinoProperty[];
282
  timezone?: string;
283
  webhookActive?: boolean;
284
  webhookUri?: string;
285
}
286

287
interface ThingUpdate {
288
  assistantId?: string;
289
  deviceId?: string;
290
  name?: string;
291
  properties?: ArduinoProperty[];
292
  timezone?: string;
293
  webhookActive?: boolean;
294
  webhookUri?: string;
295
}
296

297
interface ThingClone {
298
  includeProperties?: boolean;
299
  name: string;
300
}
301

302
interface ThingSketch {
303
  sketchVersion?: string;
304
}
305

306
interface UpdateSketch {
307
  name?: string;
308
  sketchVersion?: string;
309
}
310

311
interface ArduinoThingtemplate {
312
  name?: string;
313
  properties?: ArduinoTemplateproperty[];
314
  timezone?: string;
315
  webhookUri?: string;
316
}
317

318
interface ArduinoProperty {
319
  createdAt?: Date;
320
  href?: string;
321
  id?: string;
322
  lastValue?: any;
323
  linkedToTrigger?: boolean;
324
  maxValue?: number;
325
  minValue?: number;
326
  name?: string;
327
  permission?: PropertyPermission;
328
  persist?: boolean;
329
  tag?: number;
330
  thingId?: string;
331
  type?: PropertyType;
332
  updateParameter?: number;
333
  updateStrategy?: PropertyUpdateStrategy;
334
  updatedAt?: Date;
335
  variableName?: string;
336
}
337

338
enum PropertyPermission {
339
  READ_ONLY = 'READ_ONLY',
340
  READ_WRITE = 'READ_WRITE'
341
}
342

343
enum PropertyType {
344
  BOOL = 'BOOL',
345
  INT = 'INT',
346
  FLOAT = 'FLOAT',
347
  STRING = 'STRING',
348
  PERCENT = 'PERCENT',
349
  TEMPERATURE = 'TEMPERATURE',
350
  HUMIDITY = 'HUMIDITY',
351
  PRESSURE = 'PRESSURE'
352
}
353

354
enum PropertyUpdateStrategy {
355
  ON_CHANGE = 'ON_CHANGE',
356
  TIMED = 'TIMED'
357
}
358
```
359

360
**Complete Thing Management Example:**
361

362
```javascript
363
import ArduinoIotClient from '@arduino/arduino-iot-client';
364

365
// Initialize APIs
366
const thingsApi = new ArduinoIotClient.ThingsV2Api();
367
const thingsV2TagsApi = new ArduinoIotClient.ThingsV2TagsApi();
368

369
async function createCompleteThingSetup() {
370
  try {
371
    // Create a thing with initial properties
372
    const thing = await thingsApi.thingsV2Create({
373
      name: "Environmental Monitor",
374
      deviceId: "your-device-id",
375
      timezone: "America/New_York",
376
      webhookActive: true,
377
      webhookUri: "https://example.com/webhooks/environmental-data",
378
      properties: [
379
        {
380
          name: "Temperature",
381
          type: "TEMPERATURE",
382
          permission: "READ_ONLY",
383
          updateStrategy: "ON_CHANGE",
384
          variableName: "temperature",
385
          persist: true
386
        },
387
        {
388
          name: "Humidity",
389
          type: "HUMIDITY",
390
          permission: "READ_ONLY",
391
          updateStrategy: "TIMED",
392
          updateParameter: 30, // seconds
393
          variableName: "humidity",
394
          persist: true
395
        },
396
        {
397
          name: "Fan Control",
398
          type: "BOOL",
399
          permission: "READ_WRITE",
400
          updateStrategy: "ON_CHANGE",
401
          variableName: "fanEnabled",
402
          persist: false
403
        }
404
      ]
405
    });
406

407
    console.log('Created thing:', thing.id);
408

409
    // Add organizational tags
410
    await thingsV2TagsApi.thingsV2TagsUpsert(thing.id, {
411
      key: "location",
412
      value: "office-building-a"
413
    });
414

415
    await thingsV2TagsApi.thingsV2TagsUpsert(thing.id, {
416
      key: "type",
417
      value: "environmental-sensor"
418
    });
419

420
    await thingsV2TagsApi.thingsV2TagsUpsert(thing.id, {
421
      key: "criticality",
422
      value: "high"
423
    });
424

425
    // Create Arduino sketch for the thing
426
    await thingsApi.thingsV2CreateSketch(thing.id, {
427
      sketchVersion: "1.0.0"
428
    });
429

430
    // Verify the complete setup
431
    const completeThing = await thingsApi.thingsV2Show(thing.id, {
432
      showProperties: true
433
    });
434

435
    console.log('Thing setup complete:');
436
    console.log('- Name:', completeThing.name);
437
    console.log('- Properties:', completeThing.properties.length);
438
    console.log('- Sketch ID:', completeThing.sketchId);
439

440
    // Get template for replication
441
    const template = await thingsApi.thingsV2Template(thing.id);
442
    console.log('Template created for future replication');
443

444
    return thing;
445

446
  } catch (error) {
447
    console.error('Thing setup failed:', error);
448
    throw error;
449
  }
450
}
451

452
// Usage with error handling
453
async function manageThings() {
454
  try {
455
    // Create the setup
456
    const thing = await createCompleteThingSetup();
457

458
    // Later, clone for testing
459
    const testThing = await thingsApi.thingsV2Clone(thing.id, {
460
      name: "Environmental Monitor - Test",
461
      includeProperties: true
462
    });
463

464
    console.log('Test thing created:', testThing.id);
465

466
    // List all things to verify
467
    const allThings = await thingsApi.thingsV2List({
468
      showProperties: false,
469
      size: 100
470
    });
471

472
    console.log('Total things:', allThings.length);
473

474
  } catch (error) {
475
    if (error.status === 400) {
476
      console.error('Bad request - check thing parameters');
477
    } else if (error.status === 404) {
478
      console.error('Thing not found');
479
    } else {
480
      console.error('API Error:', error.detail || error.message);
481
    }
482
  }
483
}
484
```
485

486
**Advanced Thing Patterns:**
487

488
```javascript
489
// Bulk thing operations
490
async function bulkThingOperations() {
491
  // Get all things and filter by tags
492
  const allThings = await thingsApi.thingsV2List({ size: 1000 });
493

494
  for (const thing of allThings) {
495
    try {
496
      // Get tags for each thing
497
      const tags = await thingsV2TagsApi.thingsV2TagsList(thing.id);
498

499
      if (tags.environment === 'production') {
500
        // Update production things with monitoring webhook
501
        await thingsApi.thingsV2Update(thing.id, {
502
          webhookActive: true,
503
          webhookUri: 'https://monitoring.example.com/webhook'
504
        });
505
        console.log('Updated production thing:', thing.name);
506
      }
507
    } catch (error) {
508
      console.error(`Failed to update thing ${thing.id}:`, error);
509
    }
510
  }
511
}
512

513
// Thing lifecycle management
514
async function thingLifecycle(thingId) {
515
  // Check thing status
516
  const thing = await thingsApi.thingsV2Show(thingId);
517

518
  if (!thing.deviceId) {
519
    console.log('Thing not associated with device - associating...');
520
    // Associate with available device
521
    const availableDeviceId = await findAvailableDevice();
522
    await thingsApi.thingsV2Update(thingId, {
523
      deviceId: availableDeviceId
524
    });
525
  }
526

527
  if (!thing.sketchId) {
528
    console.log('Thing has no sketch - creating...');
529
    await thingsApi.thingsV2CreateSketch(thingId, {
530
      sketchVersion: '1.0.0'
531
    });
532
  }
533

534
  console.log('Thing lifecycle check complete');
535
}
536
```