nle-cloud-sdk 0.1.1

Unofficial asynchronous Rust SDK for the NLECloud (新大陆物联网云平台) IoT platform
Documentation
use super::sensor::{SensorBaseInfoDto, SensorDataDto};
use crate::utils::flexible_datetime_opt;
use chrono::NaiveDateTime;
use serde::{Deserialize, Serialize};

/// Basic device metadata (`DeviceBaseInfoDTO`).
#[derive(Debug, Clone, Serialize, Deserialize, Default, PartialEq)]
#[serde(rename_all = "PascalCase")]
pub struct DeviceBaseInfoDto {
    /// Device identifier.
    #[serde(rename = "DeviceID", alias = "DeviceId")]
    pub device_id: i32,

    /// Device name.
    pub name: Option<String>,

    /// Unique device tag identifier.
    pub tag: Option<String>,

    /// Communication security key.
    pub security_key: Option<String>,

    /// Associated project ID.
    #[serde(rename = "ProjectID", alias = "ProjectId")]
    pub project_id: Option<i32>,

    /// Communication protocol (e.g. TCP, MQTT, HTTP).
    pub protocol: Option<String>,

    /// Current online status.
    #[serde(default)]
    pub is_online: bool,

    /// IP address of last connection.
    #[serde(rename = "LastOnlineIP", alias = "LastOnlineIp")]
    pub last_online_ip: Option<String>,

    /// Timestamp of last online activity.
    #[serde(default, with = "flexible_datetime_opt")]
    pub last_online_time: Option<NaiveDateTime>,

    /// Geographical coordinate (e.g. "longitude,latitude").
    pub coordinate: Option<String>,

    /// Creation timestamp.
    #[serde(default, with = "flexible_datetime_opt")]
    pub create_date: Option<NaiveDateTime>,

    /// Privacy setting (false: private, true: shared).
    #[serde(default)]
    pub is_share: Option<bool>,

    /// Data reporting flag (true: can report, false: disabled).
    #[serde(default)]
    pub is_trans: Option<bool>,
}

/// Detailed device information including its sensors (`DeviceInfoDTO`).
#[derive(Debug, Clone, Serialize, Deserialize, Default, PartialEq)]
#[serde(rename_all = "PascalCase")]
pub struct DeviceInfoDto {
    /// Base device fields.
    #[serde(flatten)]
    pub base: DeviceBaseInfoDto,

    /// List of sensors attached to this device.
    #[serde(default)]
    pub sensors: Option<Vec<SensorBaseInfoDto>>,
}

/// Payload for creating or updating a device (`DeviceAddUpdateDTO`).
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(rename_all = "PascalCase")]
pub struct DeviceAddUpdateDto {
    /// Communication protocol (1: TCP, 2: MQTT, 3: HTTP).
    pub protocol: u8,

    /// Whether data reporting is enabled. Defaults to true.
    #[serde(default = "default_true")]
    pub is_trans: bool,

    /// Project ID (number) or project tag (32-character string).
    pub project_id_or_tag: String,

    /// Device name (6 to 15 characters).
    pub name: String,

    /// Device tag (6 to 30 alphanumeric characters).
    pub tag: String,

    /// Optional coordinate ("longitude,latitude").
    #[serde(skip_serializing_if = "Option::is_none")]
    pub coordinate: Option<String>,

    /// Optional device avatar/image URL.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub device_img: Option<String>,

    /// Whether device is publicly shared. Defaults to true.
    #[serde(default = "default_true")]
    pub is_share: bool,
}

fn default_true() -> bool {
    true
}

impl DeviceAddUpdateDto {
    /// Creates a new device payload with required fields and sensible defaults.
    ///
    /// - `project_id_or_tag`: Target project ID (numeric string) or project tag.
    /// - `name`: Device display name (6 to 15 characters).
    /// - `tag`: Unique device identifier tag (6 to 30 alphanumeric characters).
    /// - `protocol`: Communication protocol (1: TCP, 2: MQTT, 3: HTTP).
    pub fn new(
        project_id_or_tag: impl Into<String>,
        name: impl Into<String>,
        tag: impl Into<String>,
        protocol: u8,
    ) -> Self {
        Self {
            protocol,
            is_trans: true,
            project_id_or_tag: project_id_or_tag.into(),
            name: name.into(),
            tag: tag.into(),
            coordinate: None,
            device_img: None,
            is_share: true,
        }
    }
}

/// Query parameters for fuzzy searching devices (`DeviceFuzzyQryPagingParas`).
#[derive(Debug, Clone, Serialize, Deserialize, Default, PartialEq)]
#[serde(rename_all = "PascalCase")]
pub struct DeviceFuzzyQryPagingParas {
    /// Keyword matching ID or name from left.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub keyword: Option<String>,

    /// Comma-separated list of device IDs (max 100).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub device_ids: Option<String>,

    /// Device tag.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub tag: Option<String>,

    /// Online filter ("true" or "false").
    #[serde(skip_serializing_if = "Option::is_none")]
    pub is_online: Option<String>,

    /// Share filter ("true" or "false").
    #[serde(skip_serializing_if = "Option::is_none")]
    pub is_share: Option<String>,

    /// Project ID or 32-character project tag.
    #[serde(
        rename = "ProjectKeyWord",
        alias = "ProjectKeyword",
        skip_serializing_if = "Option::is_none"
    )]
    pub project_key_word: Option<String>,

    /// Number of items per page (default 20, max 100).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub page_size: Option<i32>,

    /// 1-based page index.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub page_index: Option<i32>,

    /// Start date (YYYY-MM-DD).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub start_date: Option<String>,

    /// End date (YYYY-MM-DD).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub end_date: Option<String>,
}

/// Device sensor telemetry points (`DeviceSensorDataDTO`).
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(rename_all = "PascalCase")]
pub struct DeviceSensorDataDto {
    /// Device identifier.
    #[serde(rename = "DeviceID", alias = "DeviceId")]
    pub device_id: i32,

    /// Device name.
    pub name: Option<String>,

    /// Telemetry data points.
    #[serde(default)]
    pub datas: Option<Vec<SensorDataDto>>,
}

/// Real-time online status of a device (`OnlineDataDTO`).
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(rename_all = "PascalCase")]
pub struct OnlineDataDto {
    /// Device identifier.
    #[serde(rename = "DeviceID", alias = "DeviceId")]
    pub device_id: i32,

    /// Device name.
    pub name: Option<String>,

    /// Online status flag.
    pub is_online: bool,

    /// IP address of last connection.
    #[serde(rename = "LastOnlineIP", alias = "LastOnlineIp")]
    pub last_online_ip: Option<String>,
}