0
# Property Operations
1

2
Property sending and listening capabilities for IoT device communication. Handle bidirectional property updates with Arduino IoT Cloud devices and things.
3

4
## Capabilities
5

6
### Send Property Values
7

8
Send property values to Arduino IoT Cloud for either multi-property or single-property clients.
9

10
#### Multi-Properties Client (User Credentials)
11

12
```typescript { .api }
13
/**
14
 * Send a property value to a specific thing
15
 * @param thingId - The ID of the thing to send the property to
16
 * @param name - The property name
17
 * @param value - The property value (string, number, boolean, or object)
18
 * @param tmp - Optional timestamp (defaults to current time)
19
 * @throws Error if thingId, name invalid, or connection issues
20
 */
21
sendProperty<T extends CloudMessageValue>(
22
  thingId: string,
23
  name: string,
24
  value: T,
25
  tmp?: number
26
): Promise<void>;
27
```
28

29
**Usage Examples:**
30

31
```typescript
32
import { ArduinoIoTCloud } from "arduino-iot-js";
33

34
const client = await ArduinoIoTCloud.connect({
35
  clientId: "your-client-id",
36
  clientSecret: "your-client-secret"
37
});
38

39
// Send simple values
40
await client.sendProperty("thing-123", "temperature", 25.5);
41
await client.sendProperty("thing-123", "humidity", 60);
42
await client.sendProperty("thing-123", "status", "active");
43
await client.sendProperty("thing-123", "enabled", true);
44

45
// Send object values
46
await client.sendProperty("thing-123", "sensor_data", {
47
  temperature: 25.5,
48
  humidity: 60,
49
  pressure: 1013.25
50
});
51

52
// Send with custom timestamp
53
const customTime = Date.now() - 60000; // 1 minute ago
54
await client.sendProperty("thing-123", "temperature", 24.8, customTime);
55
```
56

57
#### Single Property Client (Device Credentials)
58

59
```typescript { .api }
60
/**
61
 * Send a property value from this device
62
 * @param name - The property name
63
 * @param value - The property value (string, number, boolean, or object)
64
 * @param tmp - Optional timestamp (defaults to current time)
65
 * @throws Error if name invalid, no thing associated, or connection issues
66
 */
67
sendProperty<T extends CloudMessageValue>(
68
  name: string,
69
  value: T,
70
  tmp?: number
71
): Promise<void>;
72
```
73

74
**Usage Examples:**
75

76
```typescript
77
import { ArduinoIoTCloud } from "arduino-iot-js";
78

79
const client = await ArduinoIoTCloud.connect({
80
  deviceId: "your-device-id",
81
  secretKey: "your-secret-key"
82
});
83

84
// Send device property values
85
await client.sendProperty("temperature", 25.5);
86
await client.sendProperty("led_status", false);
87
await client.sendProperty("message", "Hello from device!");
88

89
// Send complex data
90
await client.sendProperty("readings", {
91
  voltage: 3.3,
92
  current: 0.5,
93
  power: 1.65
94
});
95
```
96

97
### Listen to Property Changes
98

99
Listen to property value changes with callback functions.
100

101
#### Multi-Properties Client (User Credentials)
102

103
```typescript { .api }
104
/**
105
 * Listen to property value changes from a specific thing
106
 * @param thingId - The ID of the thing to listen to
107
 * @param name - The property name to listen for
108
 * @param cb - Callback function called when property value changes
109
 * @throws Error if invalid property name or callback
110
 */
111
onPropertyValue<T extends CloudMessageValue>(
112
  thingId: string,
113
  name: string,
114
  cb: OnMessageCallback<T>
115
): void;
116
```
117

118
**Usage Examples:**
119

120
```typescript
121
import { ArduinoIoTCloud } from "arduino-iot-js";
122

123
const client = await ArduinoIoTCloud.connect({
124
  clientId: "your-client-id",
125
  clientSecret: "your-client-secret"
126
});
127

128
// Listen to simple property changes
129
client.onPropertyValue("thing-123", "temperature", (value: number) => {
130
  console.log(`Temperature updated: ${value}°C`);
131
});
132

133
client.onPropertyValue("thing-123", "status", (value: string) => {
134
  console.log(`Status changed to: ${value}`);
135
});
136

137
client.onPropertyValue("thing-123", "enabled", (value: boolean) => {
138
  console.log(`Device ${value ? 'enabled' : 'disabled'}`);
139
});
140

141
// Listen to object property changes
142
client.onPropertyValue("thing-123", "sensor_data", (value: object) => {
143
  console.log("Sensor data updated:", value);
144
  // Handle complex object data
145
  if (typeof value === 'object' && value !== null) {
146
    const data = value as any;
147
    if (data.temperature) {
148
      console.log(`New temperature: ${data.temperature}`);
149
    }
150
  }
151
});
152
```
153

154
#### Single Property Client (Device Credentials)
155

156
```typescript { .api }
157
/**
158
 * Listen to property value changes for this device
159
 * @param name - The property name to listen for
160
 * @param cb - Callback function called when property value changes
161
 * @throws Error if invalid property name or callback
162
 */
163
onPropertyValue<T extends CloudMessageValue>(
164
  name: string,
165
  cb: OnMessageCallback<T>
166
): void;
167
```
168

169
**Usage Examples:**
170

171
```typescript
172
import { ArduinoIoTCloud } from "arduino-iot-js";
173

174
const client = await ArduinoIoTCloud.connect({
175
  deviceId: "your-device-id",
176
  secretKey: "your-secret-key"
177
});
178

179
// Listen to device property changes
180
client.onPropertyValue("led_control", (value: boolean) => {
181
  console.log(`LED control: ${value ? 'ON' : 'OFF'}`);
182
  // Control physical LED based on value
183
});
184

185
client.onPropertyValue("target_temperature", (value: number) => {
186
  console.log(`Target temperature set to: ${value}°C`);
187
  // Adjust heating/cooling system
188
});
189

190
client.onPropertyValue("configuration", (value: object) => {
191
  console.log("Configuration updated:", value);
192
  // Apply new device configuration
193
});
194
```
195

196
### Device Thing Management
197

198
For single property clients (device credentials), manage the associated thing.
199

200
```typescript { .api }
201
/**
202
 * Get the thing ID associated with this device
203
 * @returns Promise resolving to the thing ID
204
 * @throws Error if no thing is associated or timeout after 10 seconds
205
 */
206
getThing(): Promise<string>;
207
```
208

209
**Usage Examples:**
210

211
```typescript
212
import { ArduinoIoTCloud } from "arduino-iot-js";
213

214
const client = await ArduinoIoTCloud.connect({
215
  deviceId: "your-device-id",
216
  secretKey: "your-secret-key"
217
});
218

219
try {
220
  const thingId = await client.getThing();
221
  console.log(`Device is associated with thing: ${thingId}`);
222

223
  // Now you can use the thing ID for other operations
224
  // Note: Single property clients typically don't need the thing ID directly
225
  // as property operations are automatically scoped to this device's thing
226
} catch (error) {
227
  console.error("No thing associated with device:", error.message);
228
}
229
```
230

231
## Data Types
232

233
### CloudMessageValue Type
234

235
Valid types for IoT property values.
236

237
```typescript { .api }
238
type CloudMessageValue = string | number | boolean | object;
239
```
240

241
### Callback Types
242

243
```typescript { .api }
244
type OnMessageCallback<T extends CloudMessageValue> = (message: T) => void;
245
```
246

247
### Token Client Interface
248

249
Additional interface for clients that use JWT token authentication, providing token management capabilities.
250

251
```typescript { .api }
252
interface ITokenCloudClient {
253
  /** Get the current JWT token */
254
  getToken(): string;
255
  /** Update the JWT token and reconnect with new token */
256
  updateToken(newToken: string): Promise<void>;
257
}
258
```
259

260
**Usage Examples:**
261

262
```typescript
263
import { ArduinoIoTCloud } from "arduino-iot-js";
264

265
// For clients that support token operations (API and Browser connections)
266
const client = await ArduinoIoTCloud.connect({
267
  token: "your-initial-jwt-token"
268
}) as ITokenCloudClient & IMultiPropertiesCloudClient;
269

270
// Get current token
271
const currentToken = client.getToken();
272
console.log("Current token:", currentToken);
273

274
// Update token when it expires
275
const newToken = await getRefreshedToken(); // Your token refresh logic
276
await client.updateToken(newToken);
277

278
// Continue using client with new token
279
await client.sendProperty("thing-123", "status", "reconnected");
280
```
281

282
## Error Handling
283

284
Common error scenarios and how to handle them:
285

286
```typescript
287
import { ArduinoIoTCloud } from "arduino-iot-js";
288

289
const client = await ArduinoIoTCloud.connect({
290
  clientId: "your-client-id",
291
  clientSecret: "your-client-secret"
292
});
293

294
// Handle property send errors
295
try {
296
  await client.sendProperty("thing-123", "temperature", 25.5);
297
} catch (error) {
298
  if (error.message.includes("timestamp must be Integer")) {
299
    console.error("Invalid timestamp provided");
300
  } else if (error.message.includes("name must be a valid string")) {
301
    console.error("Invalid property name");
302
  } else {
303
    console.error("Property send failed:", error.message);
304
  }
305
}
306

307
// Handle invalid property listeners
308
try {
309
  client.onPropertyValue("thing-123", "", (value) => {
310
    // This will throw an error due to empty property name
311
  });
312
} catch (error) {
313
  console.error("Invalid property listener:", error.message);
314
}
315
```
316

317
## Advanced Usage
318

319
### Multiple Property Listeners
320

321
```typescript
322
import { ArduinoIoTCloud } from "arduino-iot-js";
323

324
const client = await ArduinoIoTCloud.connect({
325
  token: "your-jwt-token"
326
});
327

328
// Listen to multiple properties from the same thing
329
const thingId = "thing-123";
330
const properties = ["temperature", "humidity", "pressure"];
331

332
properties.forEach(property => {
333
  client.onPropertyValue(thingId, property, (value) => {
334
    console.log(`${property} updated: ${value}`);
335

336
    // Store in database, trigger alerts, etc.
337
    handlePropertyUpdate(property, value);
338
  });
339
});
340

341
function handlePropertyUpdate(property: string, value: any) {
342
  // Custom handling logic
343
  switch (property) {
344
    case "temperature":
345
      if (value > 30) {
346
        console.warn("High temperature alert!");
347
      }
348
      break;
349
    case "humidity":
350
      if (value < 20) {
351
        console.warn("Low humidity alert!");
352
      }
353
      break;
354
  }
355
}
356
```
357

358
### Bidirectional Communication
359

360
```typescript
361
import { ArduinoIoTCloud } from "arduino-iot-js";
362

363
const client = await ArduinoIoTCloud.connect({
364
  deviceId: "your-device-id",
365
  secretKey: "your-secret-key"
366
});
367

368
// Send sensor readings periodically
369
setInterval(async () => {
370
  const temperature = readTemperatureSensor(); // Your sensor reading function
371
  const humidity = readHumiditySensor(); // Your sensor reading function
372

373
  await client.sendProperty("temperature", temperature);
374
  await client.sendProperty("humidity", humidity);
375
}, 5000);
376

377
// Listen for control commands
378
client.onPropertyValue("led_control", (enabled: boolean) => {
379
  controlLED(enabled); // Your LED control function
380

381
  // Send acknowledgment back
382
  client.sendProperty("led_status", enabled);
383
});
384

385
client.onPropertyValue("fan_speed", (speed: number) => {
386
  setFanSpeed(speed); // Your fan control function
387

388
  // Send confirmation
389
  client.sendProperty("current_fan_speed", speed);
390
});
391

392
// Mock hardware functions (replace with actual hardware control)
393
function readTemperatureSensor(): number { return 25.5; }
394
function readHumiditySensor(): number { return 60; }
395
function controlLED(enabled: boolean): void { /* control LED */ }
396
function setFanSpeed(speed: number): void { /* control fan */ }
397
```