Interfaces

Documentation Page: `ICANFDApi` Interface

1. Purpose

The ICANFDApi interface defines the contract for a proxy layer that abstracts communication with a remote CANFD device (e.g., a hardware diagnostic or data acquisition unit). It provides a standardized set of asynchronous methods to retrieve (GET) and modify (SET) device state and configuration across multiple subsystems—including USB, serial, LEDs, clocks, CAN bus, power, battery, network, recording, and event pins—while also supporting file operations (download, upload, delete) over USB. This interface decouples client code from transport-specific implementation details (e.g., HTTP, serial, or custom protocol), enabling testability and modularity in the broader system.

2. Public Interface

All methods are async and return Task<T> where T is a specific message type defined in CANFDApiProxy.Messages. Each method accepts a deviceHost (string, likely an IP or hostname) and a CancellationToken.

GET Methods (Read-Only Queries)

Method	Return Type	Description
`GetUsbTree(string deviceHost, CancellationToken ct)`	`Task<UsbTreeMessage>`	Retrieves the USB device tree (e.g., connected USB devices and their hierarchy).
`GetUsbStats(string deviceHost, CancellationToken ct)`	`Task<UsbStatsMessage>`	Retrieves USB statistics (e.g., throughput, errors).
`GetSerial(string deviceHost, CancellationToken ct)`	`Task<SerialMessage>`	Retrieves current serial port configuration/settings.
`GetLEDs(string deviceHost, CancellationToken ct)`	`Task<LEDsMessage>`	Retrieves current LED states (e.g., on/off, color).
`GetClocks(string deviceHost, CancellationToken ct)`	`Task<ClocksMessage>`	Retrieves current clock/time settings.
`GetEventPin(string deviceHost, CancellationToken ct)`	`Task<EventPinMessage>`	Retrieves current configuration/state of the event pin (e.g., armed/disarmed, trigger mode).
`GetCANConfig(string deviceHost, CancellationToken ct)`	`Task<CANConfigMessage>`	Retrieves current CAN bus configuration (e.g., bitrate, mode).
`GetCANInfo(string deviceHost, CancellationToken ct)`	`Task<CANInfoMessage>`	Retrieves static CAN hardware info (e.g., controller type, supported modes).
`GetCANState(string deviceHost, CancellationToken ct)`	`Task<CANStateMessage>`	Retrieves dynamic CAN bus state (e.g., error states, active/inactive).
`GetCANStats(string deviceHost, CancellationToken ct)`	`Task<CANStatsMessage>`	Retrieves CAN bus statistics (e.g., frames sent/received, errors).
`GetBattery(string deviceHost, CancellationToken ct)`	`Task<BatteryMessage>`	Retrieves battery status (e.g., voltage, charge level, health).
`GetServices(string deviceHost, CancellationToken ct)`	`Task<ServicesMessage>`	Retrieves list of running/available services on the device.
`GetNtp(string deviceHost, CancellationToken ct)`	`Task<NtpMessage>`	Retrieves NTP (network time protocol) configuration/status.
`GetPower(string deviceHost, CancellationToken ct)`	`Task<PowerMessage>`	Retrieves current power state (e.g., AC/battery, power mode).
`GetDeviceInfo(string deviceHost, CancellationToken ct)`	`Task<DeviceInfoMessage>`	Retrieves device identification and firmware info (e.g., model, serial, version).
`GetRecording(string deviceHost, CancellationToken ct)`	`Task<RecordingMessage>`	Retrieves recording status (e.g., running/stopped, file path, duration).
`GetNetwork(string deviceHost, CancellationToken ct)`	`Task<NetworkMessage>`	Retrieves network interface configuration (e.g., IP, gateway, DNS).

SET Methods (State Modifications)

Method	Return Type	Parameters	Description
`SetSerial(string deviceHost, SerialRequest request, CancellationToken ct)`	`Task<SerialMessage>`	`SerialRequest`	Updates serial port configuration and returns the new state.
`SetLEDs(string deviceHost, LedName led, LedCmd cmd, LedColor color, CancellationToken ct)`	`Task<LEDsPostMessage>`	`LedName`, `LedCmd`, `LedColor`	Sets a specific LED (`led`) to a command (`cmd`, e.g., ON/OFF/BLINK) and color (`color`). Returns updated LED state.
`SetClocks(string deviceHost, DateTime dateTime, CancellationToken ct)`	`Task<ClocksMessage>`	`DateTime`	Sets the device clock to `dateTime` and returns updated clock state.
`SetEventPinArm(string deviceHost, CancellationToken ct)`	`Task<EventPinMessage>`	—	Arms the event pin (e.g., enables triggering on external events).
`SetEventPinDisarm(string deviceHost, CancellationToken ct)`	`Task<EventPinMessage>`	—	Disarms the event pin (e.g., disables triggering).
`SyncClocks(string deviceHost, CancellationToken ct)`	`Task<ClocksMessage>`	—	Triggers clock synchronization (e.g., via NTP or PTP) and returns updated clock state.
`SetCANConfig(string deviceHost, CANConfigRequest request, CancellationToken ct)`	`Task<CANConfigMessage>`	`CANConfigRequest`	Updates CAN bus configuration and returns the new state.
`SetPowerOff(string deviceHost, CancellationToken ct)`	`Task<PowerMessage>`	—	Initiates device power-off sequence. Returns final power state.
`SetPowerReboot(string deviceHost, CancellationToken ct)`	`Task<PowerMessage>`	—	Initiates device reboot. Returns final power state.
`SetRecordingStart(string deviceHost, CancellationToken ct)`	`Task<RecordingMessage>`	—	Starts data recording and returns updated recording status.
`SetRecordingStop(string deviceHost, CancellationToken ct)`	`Task<RecordingMessage>`	—	Stops data recording and returns updated recording status.
`SetNetwork(string deviceHost, NetworkRequest request, CancellationToken ct)`	`Task<NetworkMessage>`	`NetworkRequest`	Updates network configuration and returns the new state.

File Operations

Method	Return Type	Parameters	Description
`Download(string deviceHost, string usbPath, string destinationDirectory, TimeSpan timeOut, CancellationToken ct)`	`Task`	`usbPath`, `destinationDirectory`, `timeOut`	Downloads a file from the device’s USB storage (`usbPath`) to the host’s `destinationDirectory`. Throws on timeout (`timeOut`).
`Upload(string deviceHost, string uploadUsbPath, string sourcefile, TimeSpan timeOut, CancellationToken ct)`	`Task<StatusMessage>`	`uploadUsbPath`, `sourcefile`, `timeOut`	Uploads `sourcefile` to the device’s USB storage at `uploadUsbPath`. Returns a `StatusMessage` indicating success/failure.
`Delete(string deviceHost, string usbPath, CancellationToken ct)`	`Task<StatusMessage>`	`usbPath`	Deletes the file at `usbPath` on the device’s USB storage. Returns a `StatusMessage`.

Note

: LedName, LedCmd, and LedColor are enums (defined elsewhere) specifying LED identifiers, commands (e.g., On, Off, Toggle), and colors (e.g., Red, Green, Blue). SerialRequest, CANConfigRequest, and NetworkRequest are request DTOs (defined in CANFDApiProxy.Requests) containing structured configuration data.

3. Invariants

Consistent deviceHost usage: All methods require a deviceHost string identifying the target device; this must be a valid address (e.g., IP or hostname) resolvable by the underlying transport.
Cancellation propagation: All methods accept a CancellationToken; implementations must respect cancellation and propagate it to underlying I/O operations.
Timeout handling for file ops: Download, Upload, and Delete accept a TimeSpan timeOut; operations exceeding this duration must fail (e.g., via OperationCanceledException or TimeoutException).
Idempotency not guaranteed: SET methods may have side effects (e.g., reboot, start/stop recording); repeated calls may not be idempotent (e.g., calling SetPowerOff twice may not be safe).
State consistency: GET methods return the current device state at the time of the call; SET methods return the new state after applying the change.

4. Dependencies

Internal Dependencies

Namespaces:
- CANFDApiProxy.Messages — Defines response message types (e.g., UsbTreeMessage, StatusMessage, LEDsMessage).
- CANFDApiProxy.Requests — Defines request DTOs (e.g., SerialRequest, CANConfigRequest, NetworkRequest).
System namespaces: System, System.Threading, System.Threading.Tasks — Standard .NET async/await and cancellation support.

External Dependencies (Inferred)

Transport layer: Not specified in the interface, but implementations (e.g., CANFDApi class) likely depend on HTTP clients, serial ports, or custom socket protocols.
Serialization: JSON or binary serialization may be used for requests/responses (not visible here, but implied by DTO usage).
Consumers: Any module requiring device control (e.g., UI, automation scripts, logging services) would depend on this interface (via DI or direct reference).

5. Gotchas

No validation on usbPath/destinationDirectory: The interface accepts arbitrary strings for file paths; implementations must handle path traversal, permissions, or invalid paths (e.g., ../secret.bin).
SetLEDs uses discrete parameters: Unlike other SET methods that take a request DTO, SetLEDs uses primitive parameters (LedName, LedCmd, LedColor). This may indicate legacy design or a simple, fixed API surface for LEDs.
SyncClocks vs SetClocks: Two distinct clock-setting methods exist:
- SetClocks sets an explicit DateTime.
- SyncClocks triggers automatic sync (e.g., via NTP). Confusing usage may lead to unintended time overrides.
No error details in return types: Most methods return state messages (e.g., PowerMessage, RecordingMessage) but not explicit error payloads. Failures likely manifest as exceptions (e.g., HttpRequestException, TimeoutException), not StatusMessage with error codes.
Download returns void: Unlike Upload/Delete, Download returns Task (no StatusMessage). Clients must infer success/failure via exception handling only.
No batch operations: Each GET/SET call is atomic; no support for bulk updates (e.g., setting multiple LEDs in one call).

None identified from source alone for other categories (e.g., thread-safety, ordering guarantees).

11 KiB Raw Permalink Blame History Unescape Escape