nle-cloud-sdk 0.1.1

Unofficial asynchronous Rust SDK for the NLECloud (新大陆物联网云平台) IoT platform
Documentation

nle-cloud-sdk

License: 0BSD Rust Crates.io Docs.rs

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 tokio and reqwest (with rustls).
  • Generic Envelope Interceptor: NLECloud wraps responses in a ResultMsg envelope. The SDK transparently unwraps successful data and maps logical API errors (non-zero Status) directly into typed SdkError::Api { status, message }.
  • Immutable Thread-Safe Client: Thread-safe (Send + Sync) NleCloudClient with fluent NleCloudClientBuilder. 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) into chrono::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:

[dependencies]
nle-cloud-sdk = { git = "https://github.com/vect-maker/nle-cloud-rust-sdk" }
tokio = { version = "1", features = ["full"] }

Quick Start

use nle_cloud_sdk::prelude::*;

#[tokio::main]
async fn main() -> Result<()> {
    // 1. Build an unauthenticated client
    let client = NleCloudClient::builder()
        .base_url("http://api.nlecloud.com")
        .build()?;

    // 2. Authenticate
    let login_res = client
        .login_with_credentials("your_account", "your_password", false)
        .await?;

    println!("Logged in as: {:?}", login_res.user_name);
    println!("Access Token: {}", login_res.access_token);

    // 3. Create an authenticated client clone
    let auth_client = client.with_token(login_res.access_token);

    // 4. Query sensors on a device
    let sensors = auth_client.get_sensors(10367, None, None).await?;
    for sensor in sensors {
        println!("Sensor: {} (Value: {})", sensor.api_tag, sensor.value);
    }

    // 5. Dispatch an actuator command (e.g. Turn fan ON = 1)
    auth_client.send_cmd(10367, "nl_fan", &1, None).await?;
    println!("Actuator command sent successfully!");

    Ok(())
}

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:

cargo test

Live Server Tests (Real Credentials)

To run end-to-end tests against the live api.nlecloud.com server:

  1. Copy .env.example to .env:
    cp .env.example .env
    
  2. Fill in your credentials:
    NLE_BASE_URL="http://api.nlecloud.com"
    NLE_ACCOUNT="your_registered_account"
    NLE_PASSWORD="your_password"
    
  3. Run the ignored live test:
    cargo test --test live_test -- --ignored --nocapture
    

Running the Demo

An example CLI application replicating the legacy test suite is included:

cargo run --example demo

You can optionally pass environment variables:

NLECLOUD_ACCOUNT="your_account" NLECLOUD_PASSWORD="your_password" cargo run --example demo

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.