0
# Property Management
1

2
Real-time property value management, timeseries data access, and property configuration. Properties are the individual data points or controls within IoT things that represent sensor readings, actuator states, or configuration values.
3

4
## Capabilities
5

6
### Core Property Operations
7

8
Primary property management functionality for CRUD operations on thing properties.
9

10
```javascript { .api }
11
class PropertiesV2Api {
12
  /**
13
   * Create a new property for a thing
14
   * @param id - Thing ID
15
   * @param property - Property configuration including type, permissions, and update strategy
16
   * @param opts - Optional parameters including organization ID
17
   * @returns Promise<ArduinoProperty> - Created property object
18
   */
19
  propertiesV2Create(id: string, property: Property, opts?: any): Promise<ArduinoProperty>;
20

21
  /**
22
   * List all properties for a thing
23
   * @param id - Thing ID
24
   * @param opts - Optional parameters including organization ID and show_deleted flag
25
   * @returns Promise<ArduinoProperty[]> - Array of property objects
26
   */
27
  propertiesV2List(id: string, opts?: any): Promise<ArduinoProperty[]>;
28

29
  /**
30
   * Get detailed information about a specific property
31
   * @param id - Thing ID
32
   * @param pid - Property ID
33
   * @param opts - Optional parameters including organization ID and show_deleted flag
34
   * @returns Promise<ArduinoProperty> - Property object with full details
35
   */
36
  propertiesV2Show(id: string, pid: string, opts?: any): Promise<ArduinoProperty>;
37

38
  /**
39
   * Update property configuration and metadata
40
   * @param id - Thing ID
41
   * @param pid - Property ID
42
   * @param property - Updated property configuration
43
   * @param opts - Optional parameters including organization ID
44
   * @returns Promise<ArduinoProperty> - Updated property object
45
   */
46
  propertiesV2Update(id: string, pid: string, property: Property, opts?: any): Promise<ArduinoProperty>;
47

48
  /**
49
   * Delete a property permanently
50
   * @param id - Thing ID
51
   * @param pid - Property ID
52
   * @param opts - Optional parameters including organization ID and force flag
53
   * @returns Promise<void>
54
   */
55
  propertiesV2Delete(id: string, pid: string, opts?: any): Promise<void>;
56

57
  /**
58
   * Publish a new value to a property (real-time data update)
59
   * @param id - Thing ID
60
   * @param pid - Property ID
61
   * @param propertyValue - New property value with optional metadata
62
   * @param opts - Optional parameters including organization ID
63
   * @returns Promise<void>
64
   */
65
  propertiesV2Publish(id: string, pid: string, propertyValue: PropertyValue, opts?: any): Promise<void>;
66

67
  /**
68
   * Get time series data for a property
69
   * @param id - Thing ID
70
   * @param pid - Property ID
71
   * @param opts - Optional parameters including time range, aggregation, and organization ID
72
   * @returns Promise<ArduinoSeriesResponse> - Time series data with statistics
73
   */
74
  propertiesV2Timeseries(id: string, pid: string, opts?: any): Promise<ArduinoSeriesResponse>;
75
}
76
```
77

78
**Usage Examples:**
79

80
```javascript
81
import ArduinoIotClient from '@arduino/arduino-iot-client';
82

83
const propertiesApi = new ArduinoIotClient.PropertiesV2Api();
84

85
// Create a temperature sensor property
86
const temperatureProperty = await propertiesApi.propertiesV2Create('thing-id', {
87
  name: 'Temperature',
88
  type: 'TEMPERATURE',
89
  permission: 'READ_ONLY',
90
  updateStrategy: 'ON_CHANGE',
91
  variableName: 'temperature',
92
  persist: true,
93
  minValue: -40,
94
  maxValue: 85
95
});
96

97
// Create a controllable LED property
98
const ledProperty = await propertiesApi.propertiesV2Create('thing-id', {
99
  name: 'LED Status',
100
  type: 'BOOL',
101
  permission: 'READ_WRITE',
102
  updateStrategy: 'ON_CHANGE',
103
  variableName: 'ledEnabled',
104
  persist: false
105
});
106

107
// Publish a new temperature reading
108
await propertiesApi.propertiesV2Publish('thing-id', temperatureProperty.id, {
109
  value: 23.5,
110
  createdAt: new Date().toISOString()
111
});
112

113
// Control the LED
114
await propertiesApi.propertiesV2Publish('thing-id', ledProperty.id, {
115
  value: true
116
});
117

118
// Get property timeseries data for the last hour
119
const timeseries = await propertiesApi.propertiesV2Timeseries('thing-id', temperatureProperty.id, {
120
  from: new Date(Date.now() - 3600000).toISOString(), // 1 hour ago
121
  to: new Date().toISOString()
122
});
123

124
console.log('Temperature data points:', timeseries.data.length);
125
```
126

127
### Property Types
128

129
Property type definitions and available property types for different sensor and actuator configurations.
130

131
```javascript { .api }
132
class PropertyTypesV1Api {
133
  /**
134
   * Get list of all available property types with their configurations
135
   * @param opts - Optional parameters including organization ID
136
   * @returns Promise<ArduinoPropertytype[]> - Array of available property types
137
   */
138
  propertyTypesV1ListTypes(opts?: any): Promise<ArduinoPropertytype[]>;
139
}
140
```
141

142
**Usage Example:**
143

144
```javascript
145
const propertyTypesApi = new ArduinoIotClient.PropertyTypesV1Api();
146

147
// Get all available property types
148
const propertyTypes = await propertyTypesApi.propertyTypesV1ListTypes();
149

150
console.log('Available property types:');
151
propertyTypes.forEach(type => {
152
  console.log(`- ${type.name}: ${type.description}`);
153
});
154

155
// Find specific property type
156
const temperatureType = propertyTypes.find(type => type.name === 'TEMPERATURE');
157
console.log('Temperature type config:', temperatureType);
158
```
159

160
### Legacy Property Operations (V1 API)
161

162
Legacy property management functionality for backward compatibility. Use PropertiesV2Api for new integrations.
163

164
```javascript { .api }
165
class PropertiesV1Api {
166
  /**
167
   * Create a new property associated to a thing (legacy)
168
   * @param id - The thing ID
169
   * @param property - Property configuration payload
170
   * @param opts - Optional parameters
171
   * @returns Promise<ArduinoProperty> - Created property object
172
   */
173
  propertiesV1Create(id: string, property: Property, opts?: any): Promise<ArduinoProperty>;
174

175
  /**
176
   * Remove a property associated to a thing (legacy)
177
   * @param id - The thing ID
178
   * @param pid - The property ID
179
   * @param opts - Optional parameters including force delete flag
180
   * @returns Promise<void>
181
   */
182
  propertiesV1Delete(id: string, pid: string, opts?: any): Promise<void>;
183

184
  /**
185
   * List properties associated to a thing (legacy)
186
   * @param id - The thing ID
187
   * @param opts - Optional parameters including showDeleted flag
188
   * @returns Promise<ArduinoProperty[]> - Array of property objects
189
   */
190
  propertiesV1List(id: string, opts?: any): Promise<ArduinoProperty[]>;
191

192
  /**
193
   * Publish a property value to MQTT as string (legacy)
194
   * @param id - The thing ID
195
   * @param pid - The property ID
196
   * @param propertyStringValue - Property value payload as string
197
   * @returns Promise<void>
198
   */
199
  propertiesV1Send(id: string, pid: string, propertyStringValue: PropertyStringValue, opts?: any): Promise<void>;
200

201
  /**
202
   * Get property details (legacy)
203
   * @param id - The thing ID
204
   * @param pid - The property ID
205
   * @param opts - Optional parameters including showDeleted flag
206
   * @returns Promise<ArduinoProperty> - Property object
207
   */
208
  propertiesV1Show(id: string, pid: string, opts?: any): Promise<ArduinoProperty>;
209

210
  /**
211
   * Update property configuration (legacy)
212
   * @param id - The thing ID
213
   * @param pid - The property ID
214
   * @param property - Updated property configuration
215
   * @returns Promise<ArduinoProperty> - Updated property object
216
   */
217
  propertiesV1Update(id: string, pid: string, property: Property, opts?: any): Promise<ArduinoProperty>;
218
}
219
```
220

221
**Migration Note:** The V1 API uses different method signatures and behavior compared to V2. For new projects, use PropertiesV2Api which provides better type safety, improved error handling, and enhanced functionality.
222

223
## Data Models
224

225
```javascript { .api }
226
interface ArduinoProperty {
227
  createdAt?: Date;
228
  href?: string;
229
  id?: string;
230
  lastValue?: any;
231
  lastValueUpdatedAt?: Date;
232
  linkedToTrigger?: boolean;
233
  maxValue?: number;
234
  minValue?: number;
235
  name?: string;
236
  permission?: PropertyPermission;
237
  persist?: boolean;
238
  tag?: number;
239
  thingId?: string;
240
  type?: PropertyType;
241
  updateParameter?: number;
242
  updateStrategy?: PropertyUpdateStrategy;
243
  updatedAt?: Date;
244
  userId?: string;
245
  variableName?: string;
246
}
247

248
interface Property {
249
  maxValue?: number;
250
  minValue?: number;
251
  name: string;
252
  permission: PropertyPermission;
253
  persist?: boolean;
254
  tag?: number;
255
  type: PropertyType;
256
  updateParameter?: number;
257
  updateStrategy: PropertyUpdateStrategy;
258
  variableName?: string;
259
}
260

261
interface PropertyValue {
262
  createdAt?: string;
263
  value: any;
264
}
265

266
interface ArduinoPropertytype {
267
  description?: string;
268
  name?: string;
269
  type?: string;
270
}
271

272
interface ArduinoSeriesResponse {
273
  aggregation?: string;
274
  countValues?: number;
275
  data?: TimeseriesDataPoint[];
276
  fromDate?: Date;
277
  interval?: number;
278
  query?: string;
279
  serieLimit?: number;
280
  status?: string;
281
  thingId?: string;
282
  toDate?: Date;
283
  values?: any[];
284
}
285

286
interface TimeseriesDataPoint {
287
  timestamp?: Date;
288
  value?: any;
289
}
290

291
enum PropertyPermission {
292
  READ_ONLY = 'READ_ONLY',
293
  READ_WRITE = 'READ_WRITE'
294
}
295

296
enum PropertyType {
297
  BOOL = 'BOOL',
298
  INT = 'INT',
299
  FLOAT = 'FLOAT',
300
  STRING = 'STRING',
301
  PERCENT = 'PERCENT',
302
  TEMPERATURE = 'TEMPERATURE',
303
  HUMIDITY = 'HUMIDITY',
304
  PRESSURE = 'PRESSURE',
305
  ACCELERATION = 'ACCELERATION',
306
  GYROSCOPE = 'GYROSCOPE',
307
  MAGNETOMETER = 'MAGNETOMETER',
308
  GPS = 'GPS',
309
  ENERGY = 'ENERGY',
310
  POWER = 'POWER',
311
  VOLTAGE = 'VOLTAGE',
312
  CURRENT = 'CURRENT',
313
  FREQUENCY = 'FREQUENCY',
314
  ANGLE = 'ANGLE',
315
  LENGTH = 'LENGTH',
316
  MASS = 'MASS',
317
  VELOCITY = 'VELOCITY',
318
  VOLUME = 'VOLUME',
319
  FLOW_RATE = 'FLOW_RATE',
320
  AREA = 'AREA',
321
  LUMINANCE = 'LUMINANCE',
322
  ILLUMINANCE = 'ILLUMINANCE',
323
  SOUND_PRESSURE_LEVEL = 'SOUND_PRESSURE_LEVEL',
324
  ELECTRIC_CHARGE = 'ELECTRIC_CHARGE',
325
  ELECTRIC_POTENTIAL = 'ELECTRIC_POTENTIAL',
326
  CAPACITANCE = 'CAPACITANCE',
327
  RESISTANCE = 'RESISTANCE',
328
  CONDUCTANCE = 'CONDUCTANCE',
329
  MAGNETIC_FIELD_STRENGTH = 'MAGNETIC_FIELD_STRENGTH',
330
  MAGNETIC_FLUX_DENSITY = 'MAGNETIC_FLUX_DENSITY',
331
  INDUCTANCE = 'INDUCTANCE'
332
}
333

334
enum PropertyUpdateStrategy {
335
  ON_CHANGE = 'ON_CHANGE',
336
  TIMED = 'TIMED'
337
}
338
```
339

340
**Comprehensive Property Management Example:**
341

342
```javascript
343
import ArduinoIotClient from '@arduino/arduino-iot-client';
344

345
const propertiesApi = new ArduinoIotClient.PropertiesV2Api();
346
const propertyTypesApi = new ArduinoIotClient.PropertyTypesV1Api();
347

348
async function createSensorThingWithProperties(thingId) {
349
  try {
350
    // Get available property types
351
    const propertyTypes = await propertyTypesApi.propertyTypesV1ListTypes();
352
    console.log('Available property types:', propertyTypes.length);
353

354
    // Create multiple sensor properties
355
    const properties = [];
356

357
    // Temperature sensor (read-only, on-change)
358
    const tempProperty = await propertiesApi.propertiesV2Create(thingId, {
359
      name: 'Temperature',
360
      type: 'TEMPERATURE',
361
      permission: 'READ_ONLY',
362
      updateStrategy: 'ON_CHANGE',
363
      variableName: 'temperature',
364
      persist: true,
365
      minValue: -40,
366
      maxValue: 85
367
    });
368
    properties.push(tempProperty);
369

370
    // Humidity sensor (read-only, timed updates every 30 seconds)
371
    const humidityProperty = await propertiesApi.propertiesV2Create(thingId, {
372
      name: 'Humidity',
373
      type: 'HUMIDITY',
374
      permission: 'READ_ONLY',
375
      updateStrategy: 'TIMED',
376
      updateParameter: 30,
377
      variableName: 'humidity',
378
      persist: true,
379
      minValue: 0,
380
      maxValue: 100
381
    });
382
    properties.push(humidityProperty);
383

384
    // Pressure sensor (read-only, on-change)
385
    const pressureProperty = await propertiesApi.propertiesV2Create(thingId, {
386
      name: 'Pressure',
387
      type: 'PRESSURE',
388
      permission: 'READ_ONLY',
389
      updateStrategy: 'ON_CHANGE',
390
      variableName: 'pressure',
391
      persist: true,
392
      minValue: 300,
393
      maxValue: 1100
394
    });
395
    properties.push(pressureProperty);
396

397
    // LED control (read-write, on-change)
398
    const ledProperty = await propertiesApi.propertiesV2Create(thingId, {
399
      name: 'Status LED',
400
      type: 'BOOL',
401
      permission: 'READ_WRITE',
402
      updateStrategy: 'ON_CHANGE',
403
      variableName: 'statusLed',
404
      persist: false
405
    });
406
    properties.push(ledProperty);
407

408
    // Fan speed control (read-write, on-change)
409
    const fanProperty = await propertiesApi.propertiesV2Create(thingId, {
410
      name: 'Fan Speed',
411
      type: 'PERCENT',
412
      permission: 'READ_WRITE',
413
      updateStrategy: 'ON_CHANGE',
414
      variableName: 'fanSpeed',
415
      persist: false,
416
      minValue: 0,
417
      maxValue: 100
418
    });
419
    properties.push(fanProperty);
420

421
    console.log(`Created ${properties.length} properties for thing ${thingId}`);
422
    return properties;
423

424
  } catch (error) {
425
    console.error('Failed to create properties:', error);
426
    throw error;
427
  }
428
}
429

430
// Simulate sensor data publishing
431
async function publishSensorData(thingId, properties) {
432
  try {
433
    const [tempProp, humidityProp, pressureProp, ledProp, fanProp] = properties;
434

435
    // Publish sensor readings
436
    await propertiesApi.propertiesV2Publish(thingId, tempProp.id, {
437
      value: 22.5 + Math.random() * 5, // Simulated temperature
438
      createdAt: new Date().toISOString()
439
    });
440

441
    await propertiesApi.propertiesV2Publish(thingId, humidityProp.id, {
442
      value: 45 + Math.random() * 20, // Simulated humidity
443
      createdAt: new Date().toISOString()
444
    });
445

446
    await propertiesApi.propertiesV2Publish(thingId, pressureProp.id, {
447
      value: 1013 + Math.random() * 20, // Simulated pressure
448
      createdAt: new Date().toISOString()
449
    });
450

451
    console.log('Published sensor data');
452

453
    // Control actuators based on sensor data
454
    const tempTimeseries = await propertiesApi.propertiesV2Timeseries(thingId, tempProp.id, {
455
      from: new Date(Date.now() - 300000).toISOString(), // Last 5 minutes
456
      to: new Date().toISOString()
457
    });
458

459
    if (tempTimeseries.data && tempTimeseries.data.length > 0) {
460
      const lastTemp = tempTimeseries.data[tempTimeseries.data.length - 1].value;
461

462
      // Turn on LED if temperature is above 25°C
463
      await propertiesApi.propertiesV2Publish(thingId, ledProp.id, {
464
        value: lastTemp > 25
465
      });
466

467
      // Set fan speed based on temperature
468
      let fanSpeed = 0;
469
      if (lastTemp > 25) {
470
        fanSpeed = Math.min(100, (lastTemp - 25) * 20); // 20% per degree above 25°C
471
      }
472

473
      await propertiesApi.propertiesV2Publish(thingId, fanProp.id, {
474
        value: fanSpeed
475
      });
476

477
      console.log(`Temperature: ${lastTemp}°C, LED: ${lastTemp > 25}, Fan: ${fanSpeed}%`);
478
    }
479

480
  } catch (error) {
481
    console.error('Failed to publish sensor data:', error);
482
  }
483
}
484

485
// Property analysis and monitoring
486
async function analyzePropertyData(thingId, propertyId, hours = 24) {
487
  try {
488
    const fromDate = new Date(Date.now() - hours * 3600000);
489
    const toDate = new Date();
490

491
    const timeseries = await propertiesApi.propertiesV2Timeseries(thingId, propertyId, {
492
      from: fromDate.toISOString(),
493
      to: toDate.toISOString(),
494
      interval: 300 // 5-minute intervals
495
    });
496

497
    if (timeseries.data && timeseries.data.length > 0) {
498
      const values = timeseries.data.map(point => parseFloat(point.value));
499

500
      const stats = {
501
        count: values.length,
502
        min: Math.min(...values),
503
        max: Math.max(...values),
504
        average: values.reduce((sum, val) => sum + val, 0) / values.length,
505
        latest: values[values.length - 1],
506
        timeRange: {
507
          from: timeseries.fromDate,
508
          to: timeseries.toDate
509
        }
510
      };
511

512
      console.log('Property statistics:', stats);
513
      return stats;
514
    } else {
515
      console.log('No data found for the specified time range');
516
      return null;
517
    }
518

519
  } catch (error) {
520
    console.error('Failed to analyze property data:', error);
521
    throw error;
522
  }
523
}
524

525
// Usage example with error handling
526
async function propertyManagementDemo(thingId) {
527
  try {
528
    // Create properties
529
    const properties = await createSensorThingWithProperties(thingId);
530

531
    // Start data publishing simulation
532
    console.log('Starting sensor data simulation...');
533

534
    for (let i = 0; i < 10; i++) {
535
      await publishSensorData(thingId, properties);
536
      await new Promise(resolve => setTimeout(resolve, 5000)); // Wait 5 seconds
537
    }
538

539
    // Analyze temperature data
540
    console.log('Analyzing temperature data...');
541
    await analyzePropertyData(thingId, properties[0].id, 1); // Last hour
542

543
    // List all properties to verify
544
    const allProperties = await propertiesApi.propertiesV2List(thingId);
545
    console.log(`Thing has ${allProperties.length} properties total`);
546

547
    allProperties.forEach(prop => {
548
      console.log(`- ${prop.name} (${prop.type}): Last value = ${prop.lastValue}`);
549
    });
550

551
  } catch (error) {
552
    if (error.status === 400) {
553
      console.error('Bad request - check property configuration');
554
    } else if (error.status === 404) {
555
      console.error('Thing or property not found');
556
    } else {
557
      console.error('Property management error:', error.detail || error.message);
558
    }
559
  }
560
}
561
```