0
# Arduino IoT JS
1

2
Arduino IoT JS is a JavaScript/TypeScript library for connecting to the Arduino IoT Cloud MQTT broker, enabling both browser and Node.js applications to interact with Arduino IoT Cloud devices and properties. It supports two connection modes: user credentials for accessing all user properties, and device credentials for single device behavior.
3

4
## Package Information
5

6
- **Package Name**: arduino-iot-js
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install arduino-iot-js`
10

11
## Core Imports
12

13
```typescript
14
import { ArduinoIoTCloud } from "arduino-iot-js";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { ArduinoIoTCloud } = require("arduino-iot-js");
21
```
22

23
Additional imports:
24

25
```typescript
26
import {
27
  ArduinoIoTCloud,
28
  CloudOptions,
29
  SenML,
30
  type APIOptions,
31
  type BrowserOptions,
32
  type CredentialsOptions,
33
  type IArduinoIoTCloudFactory,
34
  type ICloudClient,
35
  type IMultiPropertiesCloudClient,
36
  type ITokenCloudClient,
37
  type ISinglePropertyCloudClient,
38
  type CloudMessageValue
39
} from "arduino-iot-js";
40
```
41

42
## Basic Usage
43

44
### User Credentials with API Keys
45

46
```typescript
47
import { ArduinoIoTCloud } from "arduino-iot-js";
48

49
const client = await ArduinoIoTCloud.connect({
50
  clientId: "YOUR_CLIENT_ID",
51
  clientSecret: "YOUR_CLIENT_SECRET",
52
  onDisconnect: (message) => console.error(message),
53
});
54

55
// Send a value to a thing property
56
await client.sendProperty("YOUR_THING_ID", "temperature", 25.5);
57

58
// Listen to a thing property's changes
59
client.onPropertyValue("YOUR_THING_ID", "humidity", (value) => {
60
  console.log("Humidity updated:", value);
61
});
62
```
63

64
### Device Credentials
65

66
```typescript
67
import { ArduinoIoTCloud } from "arduino-iot-js";
68

69
const client = await ArduinoIoTCloud.connect({
70
  deviceId: "YOUR_DEVICE_ID",
71
  secretKey: "YOUR_SECRET_KEY",
72
  onDisconnect: (message) => console.error(message),
73
});
74

75
// Send property values as a device
76
await client.sendProperty("temperature", 25.5);
77

78
// Listen to property updates
79
client.onPropertyValue("led_status", (value) => {
80
  console.log("LED status:", value);
81
});
82
```
83

84
## Architecture
85

86
Arduino IoT JS is built around several key components:
87

88
- **Connection Factory**: `ArduinoIoTCloud` factory creates appropriate client instances based on connection options
89
- **Client Types**: Different client interfaces for multi-property (user) and single-property (device) scenarios
90
- **Builder Pattern**: Internal builders handle different authentication methods (API, token, device credentials)
91
- **Connection Layer**: MQTT connection management with WebSocket transport and reconnection logic
92
- **SenML Processing**: CBOR-encoded SenML message handling for IoT data exchange
93
- **Type Safety**: Full TypeScript support with comprehensive interfaces and type definitions
94

95
## Capabilities
96

97
### Connection Management
98

99
Core connection functionality for establishing and managing MQTT connections to Arduino IoT Cloud.
100

101
```typescript { .api }
102
interface IArduinoIoTCloudFactory {
103
  connect(options: APIOptions & Partial<CloudOptions>): Promise<IMultiPropertiesCloudClient>;
104
  connect(options: BrowserOptions & Partial<CloudOptions>): Promise<IMultiPropertiesCloudClient>;
105
  connect(options: CredentialsOptions & Partial<CloudOptions>): Promise<ISinglePropertyCloudClient>;
106
}
107
```
108

109
[Connection Management](./connection-management.md)
110

111
### Property Operations
112

113
Property sending and listening capabilities for IoT device communication.
114

115
```typescript { .api }
116
interface IMultiPropertiesCloudClient extends ICloudClient {
117
  sendProperty<T extends CloudMessageValue>(
118
    thingId: string,
119
    name: string,
120
    value: T,
121
    tmp?: number
122
  ): Promise<void>;
123
  onPropertyValue<T extends CloudMessageValue>(
124
    thingId: string,
125
    name: string,
126
    cb: OnMessageCallback<T>
127
  ): void;
128
}
129

130
interface ISinglePropertyCloudClient extends ICloudClient {
131
  sendProperty<T extends CloudMessageValue>(
132
    name: string,
133
    value: T,
134
    tmp?: number
135
  ): Promise<void>;
136
  onPropertyValue<T extends CloudMessageValue>(
137
    name: string,
138
    cb: OnMessageCallback<T>
139
  ): void;
140
}
141
```
142

143
[Property Operations](./property-operations.md)
144

145
### SenML Data Processing
146

147
SenML (Sensor Markup Language) utilities for IoT data encoding and processing.
148

149
```typescript { .api }
150
namespace SenML {
151
  export const CBOR: {
152
    encode(value: SenML[], numericKeys?: boolean): ArrayBuffer;
153
    decode(buffer: ArrayBuffer): SenML[];
154
  };
155
  export function parse(
156
    name: string,
157
    value: CloudMessageValue,
158
    timestamp: number,
159
    useCloudProtocolV2: boolean,
160
    deviceId: string
161
  ): SenML | SenML[];
162
}
163
```
164

165
[SenML Processing](./senml-processing.md)
166

167
### Error Handling
168

169
Arduino IoT Cloud specific error handling and utilities.
170

171
```typescript { .api }
172
class ArduinoCloudError extends Error {
173
  constructor(public code: number, message: string);
174
  name: string;
175
}
176
```
177

178
## Core Types
179

180
```typescript { .api }
181
type CloudMessageValue = string | number | boolean | object;
182

183
type OnMessageCallback<T extends CloudMessageValue> = (message: T) => void;
184

185

186
interface CloudOptions {
187
  host?: string;
188
  port?: string | number;
189
  useCloudProtocolV2?: boolean;
190
  ssl?: boolean;
191
  onOffline?: () => void;
192
  onConnected?: () => void;
193
  onDisconnect?: (message?: any) => void;
194
}
195

196
namespace CloudOptions {
197
  /** Default connection options */
198
  const DEFAULT: CloudOptions;
199
}
200

201
interface APIOptions {
202
  apiUrl?: string;
203
  clientId: string;
204
  audience?: string;
205
  clientSecret: string;
206
}
207

208
interface BrowserOptions {
209
  token: string;
210
}
211

212
interface CredentialsOptions {
213
  deviceId: string;
214
  secretKey: string;
215
}
216

217
interface ICloudClient {
218
  reconnect(): Promise<void>;
219
  disconnect(): Promise<void>;
220
  sendMessage(topic: string, message: string | ArrayBuffer): Promise<void>;
221
}
222

223
interface ITokenCloudClient {
224
  getToken(): string;
225
  updateToken(newToken: string): Promise<void>;
226
}
227
```