0
# Arduino IoT Client
1
2
A comprehensive Python client library for the Arduino IoT Cloud API, enabling developers to programmatically manage Arduino IoT devices, things, properties, and timeseries data. The library provides a complete set of API endpoints for device management, thing management, property handling, dashboard operations, and LoRa device support with OAuth2 authentication.
3
4
## Package Information
5
6
- **Package Name**: arduino-iot-client
7
- **Language**: Python
8
- **Installation**: `pip install arduino-iot-client`
9
- **Requires**: Python 3.10+
10
11
## Core Imports
12
13
```python
14
import iot_api_client as iot
15
from iot_api_client.configuration import Configuration
16
from iot_api_client.api import DevicesV2Api, ThingsV2Api, PropertiesV2Api
17
from iot_api_client.models import *
18
from iot_api_client.exceptions import ApiException
19
```
20
21
## Basic Usage
22
23
```python
24
import iot_api_client as iot
25
from iot_api_client.configuration import Configuration
26
from iot_api_client.api import DevicesV2Api
27
from iot_api_client.exceptions import ApiException
28
29
# Configure OAuth2 authentication
30
client_config = Configuration(host="https://api2.arduino.cc")
31
client_config.access_token = "YOUR_ACCESS_TOKEN"
32
33
# Create API client
34
client = iot.ApiClient(client_config)
35
36
# Initialize device API
37
devices_api = DevicesV2Api(client)
38
39
try:
40
# List all devices
41
devices = devices_api.devices_v2_list()
42
for device in devices:
43
print(f"{device.name} - id: {device.id} - type: {device.type}")
44
45
except ApiException as e:
46
print(f"API Error: {e}")
47
```
48
49
For organization access, specify organization ID:
50
51
```python
52
# At client level
53
client = iot.ApiClient(client_config, header_name="X-Organization", header_value="org_id")
54
55
# Or at method level
56
devices = devices_api.devices_v2_list(x_organization="org_id")
57
```
58
59
## Architecture
60
61
The Arduino IoT Client follows a resource-based API structure:
62
63
- **API Classes**: 14 specialized API classes handling different resource types
64
- **Models**: 87 Pydantic-based model classes for data validation and serialization
65
- **Core Infrastructure**: Configuration, authentication, and error handling components
66
- **OAuth2 Authentication**: Secure access with organization-level permissions
67
68
The library is auto-generated from OpenAPI specifications, ensuring consistency with the Arduino IoT Cloud API.
69
70
## Capabilities
71
72
### Device Management
73
74
Complete lifecycle management of Arduino IoT devices including creation, configuration, certificate management, OTA updates, and password handling.
75
76
```python { .api }
77
class DevicesV2Api:
78
def devices_v2_create(self, create_devices_v2_payload, x_organization=None) -> ArduinoDevicev2: ...
79
def devices_v2_list(self, across_user_ids=None, serial=None, tags=None, x_organization=None) -> List[ArduinoDevicev2]: ...
80
def devices_v2_show(self, id, x_organization=None) -> ArduinoDevicev2: ...
81
def devices_v2_update(self, id, devicev2, x_organization=None) -> ArduinoDevicev2: ...
82
def devices_v2_delete(self, id, x_organization=None) -> None: ...
83
```
84
85
[Device Management](./devices.md)
86
87
### Thing Management
88
89
Management of IoT things including creation, cloning, sketch generation, and template operations.
90
91
```python { .api }
92
class ThingsV2Api:
93
def things_v2_create(self, thing_create, force=None, x_organization=None) -> ArduinoThing: ...
94
def things_v2_list(self, across_user_ids=None, device_id=None, ids=None, tags=None, x_organization=None) -> List[ArduinoThing]: ...
95
def things_v2_clone(self, id, thing_clone, x_organization=None) -> ArduinoThing: ...
96
def things_v2_create_sketch(self, id, thing_sketch=None, x_organization=None) -> ArduinoThing: ...
97
def things_v2_delete(self, id, x_organization=None) -> None: ...
98
```
99
100
[Thing Management](./things.md)
101
102
### Property Management
103
104
Real-time and historical property data management with timeseries support and property type discovery.
105
106
```python { .api }
107
class PropertiesV2Api:
108
def properties_v2_create(self, id, model_property, x_organization=None) -> ArduinoProperty: ...
109
def properties_v2_list(self, id, show_deleted=None, x_organization=None) -> List[ArduinoProperty]: ...
110
def properties_v2_publish(self, id, pid, property_value, x_organization=None) -> None: ...
111
def properties_v2_timeseries(self, id, pid, desc=None, start=None, end=None, interval=None, x_organization=None) -> ArduinoSeriesResponse: ...
112
def properties_v2_update(self, id, pid, model_property, x_organization=None) -> ArduinoProperty: ...
113
114
class PropertyTypesV1Api:
115
def property_types_v1_list_types(self) -> List[ArduinoPropertytype]: ...
116
```
117
118
[Property Management](./properties.md)
119
120
### Dashboard Operations
121
122
Dashboard creation, sharing, widget linking, and template management.
123
124
```python { .api }
125
class DashboardsV2Api:
126
def dashboards_v2_create(self, dashboardv2, x_organization=None) -> ArduinoDashboardv2: ...
127
def dashboards_v2_list(self, x_organization=None) -> List[ArduinoDashboardv2]: ...
128
def dashboards_v2_clone(self, dashboard_id, x_organization=None) -> ArduinoDashboardv2: ...
129
def dashboards_v2_share(self, id, sharerequest, x_organization=None) -> None: ...
130
def dashboards_v2_link(self, id, widget_id, widgetlink, x_organization=None) -> None: ...
131
```
132
133
[Dashboard Operations](./dashboards.md)
134
135
### Timeseries Data
136
137
Advanced querying capabilities for timeseries data with batch operations and historical data access.
138
139
```python { .api }
140
class SeriesV2Api:
141
def series_v2_batch_query_raw(self, batch_query_raw_requests_media_v1, x_organization=None) -> ArduinoSeriesRawResponse: ...
142
def series_v2_batch_query_sampling(self, batch_query_sampled_requests_media_v1, x_organization=None) -> ArduinoSeriesSampledResponse: ...
143
def series_v2_batch_query_raw_last_value(self, batch_last_value_requests_media_v1, x_organization=None) -> ArduinoSeriesRawLastValueResponse: ...
144
def series_v2_historic_data(self, historic_data_request, x_organization=None) -> ArduinoSeriesResponse: ...
145
```
146
147
[Timeseries Data](./series.md)
148
149
### LoRa Connectivity
150
151
LoRa device management and frequency plan configuration for long-range IoT applications.
152
153
```python { .api }
154
class LoraDevicesV1Api:
155
def lora_devices_v1_create(self, create_lora_devices_v1_payload, x_organization=None) -> ArduinoLoradevicev1: ...
156
def lora_devices_v1_list(self, x_organization=None) -> List[ArduinoLoradevicev1]: ...
157
def lora_devices_v1_show(self, id, x_organization=None) -> ArduinoLoradevicev1: ...
158
159
class LoraFreqPlanV1Api:
160
def lora_freq_plan_v1_list(self, x_organization=None) -> List[ArduinoLorafreqplanv1]: ...
161
```
162
163
[LoRa Connectivity](./lora.md)
164
165
## Authentication
166
167
OAuth2 authentication with Arduino IoT Cloud API:
168
169
```python { .api }
170
class Configuration:
171
def __init__(self, host="https://api2.arduino.cc", access_token=None, **kwargs): ...
172
173
# Properties
174
host: str
175
access_token: str
176
api_key: Dict[str, str]
177
username: str
178
password: str
179
client_side_validation: bool
180
```
181
182
## Error Handling
183
184
Comprehensive exception hierarchy for robust error handling:
185
186
```python { .api }
187
class ApiException(Exception): ...
188
class BadRequestException(ApiException): ... # HTTP 400
189
class UnauthorizedException(ApiException): ... # HTTP 401
190
class ForbiddenException(ApiException): ... # HTTP 403
191
class NotFoundException(ApiException): ... # HTTP 404
192
class ServiceException(ApiException): ... # HTTP 5xx
193
```
194
195
## Core Types
196
197
```python { .api }
198
class ApiClient:
199
def __init__(self, configuration=None, header_name=None, header_value=None, cookie=None): ...
200
201
class ApiResponse:
202
status_code: int
203
headers: Dict[str, str]
204
data: Any
205
raw_data: bytes
206
```