nle-cloud-sdk
An idiomatic, asynchronous, thread-safe Rust SDK crate for the NLECloud (新大陆物联网云平台) IoT platform.
[!IMPORTANT] Disclaimer: This is an independent, unofficial, community-developed open-source Rust library. "NLECloud" and "新大陆" are trademarks and property of Newland Educational / Newland Cloud (新大陆教育). This project is not officially affiliated with, maintained by, or endorsed by Newland.
Features
- Asynchronous & Non-blocking: Powered by
tokioandreqwest(withrustls). - Generic Envelope Interceptor: NLECloud wraps responses in a
ResultMsgenvelope. The SDK transparently unwraps successful data and maps logical API errors (non-zeroStatus) directly into typedSdkError::Api { status, message }. - Immutable Thread-Safe Client: Thread-safe (
Send + Sync)NleCloudClientwith fluentNleCloudClientBuilder. Easily clone authenticated instances with.with_token(...). - Complete DTO Coverage: Strongly typed data models matching all upstream endpoints (Auth, Projects, Devices, Sensors, Actuators, Cameras, Telemetry Points, Paging).
- Flexible Timestamps: Automatically parses multiple timestamp formats (
YYYY-MM-DD HH:mm:ss,YYYY-MM-DD HH:mm, ISO 8601) intochrono::NaiveDateTime. - Zero Attribution Required: Released under the 0BSD license—freely use, modify, and share without requiring attribution.
Installation
Add this crate to your Cargo.toml:
[]
= { = "https://github.com/vect-maker/nle-cloud-rust-sdk" }
= { = "1", = ["full"] }
Quick Start
use *;
async
API Coverage
All RESTful endpoints documented at http://www.nlecloud.com/doc/api are supported:
| Category | Method | Endpoint Description |
|---|---|---|
| Auth | POST /users/login |
Account login and token retrieval |
POST /users/getcurrenttoken |
Inspect currently active token | |
| Projects | GET /projects/{projectId} |
Query single project metadata |
GET /projects |
Fuzzy search projects with pagination | |
POST /projects |
Create a new project | |
PUT /projects/{projectId} |
Update an existing project | |
DELETE /projects |
Batch delete projects | |
GET /projects/{projectId}/sensors |
Query all sensors across project devices | |
GET /projects/{projectId}/sensorsrealtimedata |
Query real-time sensor streams | |
| Devices | GET /devices/datas |
Batch query latest sensor readings |
GET /devices/status |
Batch query online/offline status | |
GET /devices/simulationdatas |
Batch query simulation telemetry data | |
GET /devices/{deviceId} |
Query single device metadata and sensors | |
GET /devices |
Fuzzy search devices with pagination | |
POST /devices |
Add a new device | |
PUT /devices/{deviceId} |
Update device configuration | |
DELETE /devices/{deviceId} |
Delete a device | |
| Sensors | GET /devices/{deviceId}/sensors/{apiTag} |
Query a specific sensor/actuator |
GET /devices/{deviceId}/sensors |
Query sensors on a device | |
POST /devices/{deviceId}/sensors |
Add a sensor, actuator, or camera | |
PUT /devices/{deviceId}/sensors/{apiTag} |
Update a sensor, actuator, or camera | |
DELETE /devices/{deviceId}/sensors/{apiTag} |
Delete a sensor | |
| Datas | POST /devices/{deviceId}/datas |
Upload/publish sensor telemetry points |
GET /devices/{deviceId}/datas |
Query historical telemetry with pagination | |
GET /devices/{deviceId}/datas/grouping |
Time-bucketed aggregation (MIN, MAX, COUNT) | |
GET /devices/{deviceId}/Datas/SensorDataExecLog |
Query actuator command execution history | |
| Commands | POST /Cmds |
Dispatch command to an actuator |
Testing
Mock Integration Tests (Offline)
Hermetic integration tests using wiremock:
Live Server Tests (Real Credentials)
To run end-to-end tests against the live api.nlecloud.com server:
- Copy
.env.exampleto.env: - Fill in your credentials:
NLE_BASE_URL="http://api.nlecloud.com" NLE_ACCOUNT="your_registered_account" NLE_PASSWORD="your_password" - Run the ignored live test:
Running the Demo
An example CLI application replicating the legacy test suite is included:
You can optionally pass environment variables:
NLECLOUD_ACCOUNT="your_account" NLECLOUD_PASSWORD="your_password"
License
This project is licensed under the BSD Zero Clause License (0BSD).
You are free to use, copy, modify, distribute, and integrate this software for any purpose, with or without fee, without any requirement to provide attribution.
See LICENSE or LICENSE.md for full terms.