noisedestroyers/DP44
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
bc3ac1d4c9bfb56c00ec892a5a321bb0e5dcc55d
DP44/enriched-qwen3-coder-next/DataPRO/CanFDApiProxy/Messages.md
noisedestroyers bc3ac1d4c9 init
2026-04-17 14:55:32 -04:00

129 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
source_files:
- DataPRO/CanFDApiProxy/Messages/StatusMessage.cs
- DataPRO/CanFDApiProxy/Messages/ErrorMessage.cs
- DataPRO/CanFDApiProxy/Messages/NtpMessage.cs
- DataPRO/CanFDApiProxy/Messages/LEDsPostMessage.cs
- DataPRO/CanFDApiProxy/Messages/DiagnosticsMessage.cs
- DataPRO/CanFDApiProxy/Messages/ClocksMessage.cs
- DataPRO/CanFDApiProxy/Messages/DeviceInfoMessage.cs
- DataPRO/CanFDApiProxy/Messages/SerialMessage.cs
- DataPRO/CanFDApiProxy/Messages/ServicesMessage.cs
- DataPRO/CanFDApiProxy/Messages/NetworkMessage.cs
- DataPRO/CanFDApiProxy/Messages/CalibrationMessage.cs
- DataPRO/CanFDApiProxy/Messages/CANInfoMessage.cs
- DataPRO/CanFDApiProxy/Messages/UsbTreeMessage.cs
- DataPRO/CanFDApiProxy/Messages/BatteryMessage.cs
- DataPRO/CanFDApiProxy/Messages/RecordingMessage.cs
- DataPRO/CanFDApiProxy/Messages/PowerMessage.cs
- DataPRO/CanFDApiProxy/Messages/EventPinMessage.cs
- DataPRO/CanFDApiProxy/Messages/CANStateMessage.cs
- DataPRO/CanFDApiProxy/Messages/LEDsMessage.cs
- DataPRO/CanFDApiProxy/Messages/CANStatsMessage.cs
- DataPRO/CanFDApiProxy/Messages/CANConfigMessage.cs
- DataPRO/CanFDApiProxy/Messages/UsbStatsMessage.cs
- DataPRO/CanFDApiProxy/Messages/CANInfoInternal.cs
generated_at: "2026-04-16T04:02:31.640911+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "7eb2e08a0b1b3deb"
---
# CANFDApiProxy.Messages Module Documentation
---
## 1. Purpose
This module defines a set of data transfer objects (DTOs) used for serializing and deserializing JSON payloads exchanged with the CANFD API proxy service. These message classes represent structured responses and requests for device status, configuration, diagnostics, hardware state (e.g., LEDs, power, battery, clocks), network settings, CAN bus statistics, USB device tree, and calibration data. They serve as the contract between the API proxy layer and higher-level components (e.g., UI, logging, control logic), enabling type-safe handling of RESTful or IPC-based communication endpoints.
---
## 2. Public Interface
All classes reside in the `CANFDApiProxy.Messages` namespace and are `public`. No classes are `internal` in the public interface (though `CANInfoInternal` is declared `internal`, it is not part of the public API surface).
### Message Classes
| Class | Properties | Description |
|-------|------------|-------------|
| `StatusMessage` | `string status` | Generic status response. |
| `ErrorMessage` | `string Error` | Error response payload. |
| `NtpMessage` | `string Ntp`, `string Fallback` | NTP synchronization status and fallback address. |
| `LEDsPostMessage` | `string status`, `string reply` | Response to an LED control POST request. |
| `DiagnosticsMessageRequest` | `string format` | Request to retrieve diagnostics in a specified format (e.g., `"json"`, `"text"`). Includes custom `ToString()` override. |
| `DeviceInfoMessage` | `string Kernel_version`, `string Os_release`, `string Serial_number`, `string Version_number` | Device firmware and OS metadata. |
| `SerialMessage` | `string Serial`, `string Status` | Serial port status and current value. Includes custom `ToString()` override. |
| `ServicesMessage` | `Service[] services` | List of managed services with `Enabled`, `Name`, `Status`. |
| `NetworkMessage` | `string Current_address`, `bool Dhcp`, `string Interface`, `string Mac_address`, `string Set_address`, `string Ok` | Network interface configuration and status. |
| `CalibrationMessage` | `int Calibration_date`, `string Calibration_date_string` | Calibration timestamp (numeric and human-readable). Includes custom `ToString()` override. |
| `CANInfoMessage` | `List<CANInfo> CANInfoList` | List of CAN interface info objects (`Name`, `Info`). |
| `UsbTreeMessage` | `Child[] children`, `string name`, `string path`, `string type` | Hierarchical USB device tree node. `Child` has same fields and recursive `children`. |
| `BatteryMessage` | `decimal LoadV`, `decimal Current`, `decimal Power`, `decimal Percent`, `bool Enable` | Battery telemetry. Includes custom `ToString()` override. |
| `RecordingMessage` | `string Recording`, `bool Autoarm`, `string Recording_dir`, `string Ok`, `string Reply` | Recording state and configuration. Includes custom `ToString()` override. |
| `PowerMessage` | `bool Battery_enable`, `bool Nvin_pin`, `bool On_pin`, `bool Power_fault`, `string Status` | Power subsystem state. Includes custom `ToString()` override. |
| `EventPinMessage` | `bool? Armed`, `bool? Event`, `bool? Event_pin`, `string File_name`, `string Ok`, `string Reply` | Event pin trigger state and file context. Includes custom `ToString()` override. |
| `CANStateMessage` | `List<CANState> CANStateList` | List of CAN interface states (`Name`, `string State`, `float Last_updated`). |
| `LEDsMessage` | `List<LED> LEDs`, `Battery Battery`, `Pwr Pwr`, `Status Status`, `Sts Sts` | LED states (color per LED), plus global LED groups. `LED` has `Name`, `Red`, `Green`, `Blue`. |
| `CANStatsMessage` | `List<CANStats> CANStatsList` | List of CAN interface statistics (`Name`, `Last_updated`, `Std_data`, `Std_remote`, `Ext_data`, `Ext_remote`, `Err_frame`, `Bus_load`, `Overruns`). |
| `CANConfigMessage` | `List<CANConfig> CANConfigList`, `Pipe Pipe`, `string Status` | CAN bus configuration for up to 4 interfaces (`CANConfig`), plus pipe path and status. Includes `CreateCanConfigRequest()` factory method (see below). |
| `UsbStatsMessage` | `Filesystem Filesystem`, `Swissbit Swissbit`, `Traffic Traffic` | USB storage health and throughput stats. Nested types: `Filesystem`, `Swissbit`, `Lifetime_Info`, `Spare_Block_Info`, `Erase_Info`, `Average_Erase_Count`, `Max_Erase_Count`, `Rated_Erase_Count`, `Traffic`. |
### Factory Method
| Method | Signature | Description |
|--------|-----------|-------------|
| `CANConfigMessage.CreateCanConfigRequest` | `static CANConfigRequest CreateCanConfigRequest(CANConfigMessage canConfigMessage)` | Converts a `CANConfigMessage` into a `CANConfigRequest` (from `CANFDApiProxy.Requests`). Maps the first four `CANConfig` entries to `can1`–`can4` fields. Returns a `CANConfigRequest` with `Status` set to exception message on failure. |
### Helper Classes (Public)
| Class | Properties | Description |
|-------|------------|-------------|
| `Service` | `bool Enabled`, `string Name`, `string Status` | Represents a service in `ServicesMessage`. |
| `LED` | `string Name`, `bool Red`, `bool Green`, `bool Blue` | Represents a single LED in `LEDsMessage`. |
| `CANInfo` | `string Name`, `string Info` | Represents CAN interface info in `CANInfoMessage`. Constructor enforces non-null `name`/`info`. |
| `CANState` | `string Name`, `string State`, `float Last_updated` | Represents CAN interface state in `CANStateMessage`. Constructor enforces non-null `name`/`state`. |
| `CANStats` | `string Name`, `float Last_updated`, `int Std_data`, `int Std_remote`, `int Ext_data`, `int Ext_remote`, `int Err_frame`, `float Bus_load`, `int Overruns` | Represents CAN interface stats in `CANStatsMessage`. Constructor enforces non-null `name`. |
| `CANConfig` | `string Name`, `int Base_or_arb_bitrate`, `int Base_or_arb_sjw`, `int Data_bitrate`, `int Data_sjw`, `string Filetype`, `bool Included`, `bool Is_fd` | Represents CAN interface configuration in `CANConfigMessage`. Constructor enforces non-null `name`/`filetype`. |
> **Note**: `CANConfigRequest` is imported from `CANFDApiProxy.Requests` and is not defined here. Its structure is inferred from usage in `CreateCanConfigRequest`.
---
## 3. Invariants
- **Non-null `Name` fields**: In `CANInfo`, `CANState`, `CANStats`, and `CANConfig`, the `Name` property is set via constructor and is read-only (`get;` only), implying it must be non-null at construction and never changed afterward.
- **Fixed CAN interface count**: `CANConfigMessage.CreateCanConfigRequest` assumes exactly 4 CAN interfaces (`can1`–`can4`) and accesses `CANConfigArray[0]` through `[3]`. Index out-of-range exceptions will occur if the list has fewer than 4 items.
- **Nullable booleans**: Fields like `Armed`, `Event`, `Event_pin`, `Rtc_present`, `Rtc_setup` are declared as `bool?`, indicating they may be absent or unknown.
- **Numeric precision**: Battery metrics (`LoadV`, `Current`, `Power`, `Percent`) use `decimal` for precision; CAN stats use `int` for counters and `float` for time/load metrics.
- **String formatting**: `Calibration_date` is an `int` (likely Unix epoch), while `Calibration_date_string` provides human-readable form—both must be consistent.
- **LED color state**: In `LEDsMessage.LED`, each LED’s color (`Red`, `Green`, `Blue`) is a `bool`, implying binary on/off per channel.
---
## 4. Dependencies
### Imports/References
- `System.Collections.Generic` (used in `CANInfoMessage`, `CANStateMessage`, `CANStatsMessage`, `LEDsMessage`)
- `System.Text` (used in `CANConfigMessage.ToString()` via `StringBuilder`)
- `CANFDApiProxy.Requests` (used in `CANConfigMessage.CreateCanConfigRequest()` to construct `CANConfigRequest`)
### Inferred Usage
- **Serialization**: All classes are simple POCOs with public setters, designed for JSON deserialization (e.g., via `System.Text.Json` or `Newtonsoft.Json`).
- **API layer**: These messages are likely consumed/produced by HTTP handlers, gRPC services, or IPC endpoints in `CANFDApiProxy`.
- **Request conversion**: `CreateCanConfigRequest` implies tight coupling with `CANFDApiProxy.Requests.CANConfigRequest`, suggesting this module is part of a request/response pipeline.
---
## 5. Gotchas
- **`CANConfigMessage` assumes 4 CAN interfaces**: Hardcoded array indices `[0]`–`[3]` in `CreateCanConfigRequest` will throw `IndexOutOfRangeException` if the input `CANConfigList` has fewer than 4 items. No validation is performed.
- **Inconsistent property casing**: Some properties use `snake_case` (`status`, `Error`, `Calibration_date`, `Current_address`) while others use `PascalCase` (`Kernel_version`, `Serial_number`). This may reflect JSON payload conventions but can cause deserialization issues if not handled consistently (e.g., via `JsonPropertyName` attributes).
- **`CANInfoInternal` is internal**: Though defined in the same file, `CANInfoInternal` and its nested types (`Can1`, `Can2`, etc.) are `internal` and not part of the public API. Do not rely on them externally.
- **Missing null-safety**: None of the classes perform null checks in constructors or setters. Passing `null` to `CANInfo`/`CANState`/`CANStats`/`CANConfig` constructors will result in `NullReferenceException` at runtime.
- **`Calibration_date` type**: `int` for a date is ambiguous—could be Unix timestamp (seconds) or `YYYYMMDD` integer. Clarify with API spec.
- **`Ok` vs `status`/`Status`**: Multiple classes use `Ok` (e.g., `NetworkMessage`, `RecordingMessage`, `EventPinMessage`) while others use `status`/`Status`. This inconsistency may indicate legacy naming or different API versions.
- **`UsbStatsMessage` complexity**: Deeply nested types (`Lifetime_Info`, `Spare_Block_Info`, etc.) suggest complex SSD health reporting. Ensure all fields are populated before use; missing nested objects may cause `NullReferenceException`.
- **`ToString()` overrides**: Several classes override `ToString()` for debugging, but these are not used in serialization. Do not rely on them for logging or persistence.
None identified beyond the above.
Reference in New Issue View Git Blame Copy Permalink