11 KiB
11 KiB
source_files, generated_at, model, schema_version, sha256
| source_files | generated_at | model | schema_version | sha256 | |||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
2026-04-16T04:02:31.640911+00:00 | Qwen/Qwen3-Coder-Next-FP8 | 1 | 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
:
CANConfigRequestis imported fromCANFDApiProxy.Requestsand is not defined here. Its structure is inferred from usage inCreateCanConfigRequest.
3. Invariants
- Non-null
Namefields: InCANInfo,CANState,CANStats, andCANConfig, theNameproperty 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.CreateCanConfigRequestassumes exactly 4 CAN interfaces (can1–can4) and accessesCANConfigArray[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_setupare declared asbool?, indicating they may be absent or unknown. - Numeric precision: Battery metrics (
LoadV,Current,Power,Percent) usedecimalfor precision; CAN stats useintfor counters andfloatfor time/load metrics. - String formatting:
Calibration_dateis anint(likely Unix epoch), whileCalibration_date_stringprovides human-readable form—both must be consistent. - LED color state: In
LEDsMessage.LED, each LED’s color (Red,Green,Blue) is abool, implying binary on/off per channel.
4. Dependencies
Imports/References
System.Collections.Generic(used inCANInfoMessage,CANStateMessage,CANStatsMessage,LEDsMessage)System.Text(used inCANConfigMessage.ToString()viaStringBuilder)CANFDApiProxy.Requests(used inCANConfigMessage.CreateCanConfigRequest()to constructCANConfigRequest)
Inferred Usage
- Serialization: All classes are simple POCOs with public setters, designed for JSON deserialization (e.g., via
System.Text.JsonorNewtonsoft.Json). - API layer: These messages are likely consumed/produced by HTTP handlers, gRPC services, or IPC endpoints in
CANFDApiProxy. - Request conversion:
CreateCanConfigRequestimplies tight coupling withCANFDApiProxy.Requests.CANConfigRequest, suggesting this module is part of a request/response pipeline.
5. Gotchas
CANConfigMessageassumes 4 CAN interfaces: Hardcoded array indices[0]–[3]inCreateCanConfigRequestwill throwIndexOutOfRangeExceptionif the inputCANConfigListhas fewer than 4 items. No validation is performed.- Inconsistent property casing: Some properties use
snake_case(status,Error,Calibration_date,Current_address) while others usePascalCase(Kernel_version,Serial_number). This may reflect JSON payload conventions but can cause deserialization issues if not handled consistently (e.g., viaJsonPropertyNameattributes). CANInfoInternalis internal: Though defined in the same file,CANInfoInternaland its nested types (Can1,Can2, etc.) areinternaland 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
nulltoCANInfo/CANState/CANStats/CANConfigconstructors will result inNullReferenceExceptionat runtime. Calibration_datetype:intfor a date is ambiguous—could be Unix timestamp (seconds) orYYYYMMDDinteger. Clarify with API spec.Okvsstatus/Status: Multiple classes useOk(e.g.,NetworkMessage,RecordingMessage,EventPinMessage) while others usestatus/Status. This inconsistency may indicate legacy naming or different API versions.UsbStatsMessagecomplexity: 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 causeNullReferenceException.ToString()overrides: Several classes overrideToString()for debugging, but these are not used in serialization. Do not rely on them for logging or persistence.
None identified beyond the above.