/* * @file protocol.h * @brief * * Created: 07.05.2026 10:15:36 * Author: ThePetrovich * * Copyright YKSA - Sakha Aerospace Systems, LLC. * See the LICENSE file for details. * * SPDX-License-Identifier: BSD-3-Clause */ #ifndef PROTOCOL_H #define PROTOCOL_H #include "config.h" #include /* * @details * General Protocol Description: * - All commands are initiated by the host * - Command format: [CMD (2 bytes)][Length (2 bytes)][Payload (variable)][CRC16 (2 bytes)] * - CMD: 2 bytes command identifier (e.g., 'HV' for set potentiometers) * - Length: 2 bytes unsigned integer indicating the length of the payload in bytes * - Payload: Variable length data specific to the command * - CRC16: 2 bytes CRC16-XMODEM checksum of the CMD, Length, and Payload fields * - Response: For commands that require a response, the device will send back a similar structured * message with the appropriate CMD and payload. Otherwise, it should send an acknowledgment * (e.g., 'ACK') or an error response if the command is invalid. * - If a valid command is received, but cannot be executed (e.g. locked state, parameters out of range), * the device should send a command failure response (e.g., 'NAK') without performing any action. * - Error Handling: If a command is malformed (e.g., incorrect CRC, invalid length), the device will * ignore the command and should send an error response (e.g., 'ERR') to the host. * The device should not perform any action if the command is invalid. * Example Command: Set Potentiometers * - CMD: 'HV' (0x48 0x56) * - Length: 3 (0x00 0x03) * - Payload: [HV_POT (1 byte)][AMP_POT (1 byte)][DET_POT (1 byte)] * - CRC16: Calculated over 'HV', Length, and Payload * Response: 'ACK' if successful, 'NAK' if parameters are out of safe range, 'ERR' if command is malformed */ uint16_t protocol_crc16_xmodem(uint8_t *data, uint16_t len); typedef struct protocol_header_t { uint16_t cmd; uint16_t length; } __attribute__((packed)) protocol_header_t; void protocol_send_header(uint16_t cmd, uint16_t length); void protocol_send_ack(void); void protocol_send_nak(void); void protocol_send_error(void); void protocol_send_message(uint16_t cmd, void *payload, uint16_t length); /* * @brief Firmware version command and response structure * @param[out] major Firmware major version * @param[out] minor Firmware minor version */ #define CMD_FIRMWARE_VERSION 0x7600 typedef struct protocol_firmware_version_response_t { uint8_t major; uint8_t minor; } __attribute__((packed)) protocol_firmware_version_response_t; void handle_version_command(void *payload, uint16_t length); /* * @brief Light sensor presence command and response structure * @param[out] total_detected Total number of sensors detected across all buses * @param[out] bus_x_count Number of sensors detected on bus X * @param[out] bus_x_neg_addr I2C address of negative sensor on bus X (0 if not present) * @param[out] bus_x_pos_addr I2C address of positive sensor on bus X (0 if not present) * @param[out] bus_y_count Number of sensors detected on bus Y * @param[out] bus_y_neg_addr I2C address of negative sensor on bus Y (0 if not present) * @param[out] bus_y_pos_addr I2C address of positive sensor on bus Y (0 if not present) * @param[out] bus_z_count Number of sensors detected on bus Z * @param[out] bus_z_neg_addr I2C address of negative sensor on bus Z (0 if not present) * @param[out] bus_z_pos_addr I2C address of positive sensor on bus Z (0 if not present) */ #define CMD_LIGHT_SENSOR_PRESENCE 0x6C00 typedef struct protocol_light_sensor_presence_response_t { uint8_t total_detected; uint8_t bus_x_count; uint8_t bus_x_neg_addr; uint8_t bus_x_pos_addr; uint8_t bus_y_count; uint8_t bus_y_neg_addr; uint8_t bus_y_pos_addr; uint8_t bus_z_count; uint8_t bus_z_neg_addr; uint8_t bus_z_pos_addr; } __attribute__((packed)) protocol_light_sensor_presence_response_t; void handle_light_sensor_presence_command(void *payload, uint16_t length); /* * @brief Read light sensor data command and response structure * @param[in] channel Spectral channel (0 = red, 1 = green, 2 = blue, 3 = IR, 4 = green2, 5 = composite visible, 6 = * composite all) * @param[out] bus_x_neg_channel_value Channel value for negative sensor on bus X * @param[out] bus_x_pos_channel_value Channel value for positive sensor on bus X * @param[out] bus_y_neg_channel_value Channel value for negative sensor on bus Y * @param[out] bus_y_pos_channel_value Channel value for positive sensor on bus Y * @param[out] bus_z_neg_channel_value Channel value for negative sensor on bus Z * @param[out] bus_z_pos_channel_value Channel value for positive sensor on bus Z */ #define CMD_READ_LIGHT_SENSORS 0x7200 typedef struct protocol_read_light_sensors_command_t { uint8_t channel; } __attribute__((packed)) protocol_read_light_sensors_command_t; typedef struct protocol_read_light_sensors_response_t { uint16_t bus_x_neg_channel_value; uint16_t bus_x_pos_channel_value; uint16_t bus_y_neg_channel_value; uint16_t bus_y_pos_channel_value; uint16_t bus_z_neg_channel_value; uint16_t bus_z_pos_channel_value; } __attribute__((packed)) protocol_read_light_sensors_response_t; void handle_read_light_sensors_command(void *payload, uint16_t length); /* * @brief Get configuration command and response structure * @param[out] config Current device configuration */ #define CMD_GET_CONFIGURATION 0x6D00 typedef struct protocol_get_configuration_response_t { config_t config; } __attribute__((packed)) protocol_get_configuration_response_t; void handle_get_configuration_command(void *payload, uint16_t length); /* * @brief Set configuration command and response structure * @param[in] config New device configuration to apply */ #define CMD_SET_CONFIGURATION 0x7D00 typedef struct protocol_set_configuration_command_t { config_t config; } __attribute__((packed)) protocol_set_configuration_command_t; void handle_set_configuration_command(void *payload, uint16_t length); /* * @brief Set potentiometers command and response structure * @param[in] hv_pot High voltage potentiometer value * @param[in] amp_pot Amplifier potentiometer value * @param[in] det_pot Detector potentiometer value */ #define CMD_SET_POTENTIOMETERS 0x7D01 typedef struct protocol_set_potentiometers_command_t { uint8_t hv_pot; uint8_t amp_pot; uint8_t det_pot; } __attribute__((packed)) protocol_set_potentiometers_command_t; void handle_set_potentiometers_command(void *payload, uint16_t length); /* * @brief Set calibration data command and response structure * @param[in] adccal0 ADC offset at GND * @param[in] adccal3 ADC reading at 3.0V reference * @param[in] tempcal Temperature calibration value * @param[in] tempdrift_mvK Temperature drift compensation in mV/K */ #define CMD_SET_CALIBRATION 0x7D02 typedef struct protocol_set_calibration_command_t { uint16_t adccal0; uint16_t adccal3; uint16_t tempcal; uint16_t tempdrift_mvK; } __attribute__((packed)) protocol_set_calibration_command_t; void handle_set_calibration_command(void *payload, uint16_t length); /* * @brief Set flags command and response structure * @param[in] flags Configuration flags to set (e.g., oversampling, channel mode, temperature compensation) */ #define CMD_SET_FLAGS 0x7D03 typedef struct protocol_set_flags_command_t { uint8_t flags; } __attribute__((packed)) protocol_set_flags_command_t; /* * @brief Set temperature drift compensation ranges command and response structure * @param[in] tempdrift_pot_hv_low Low threshold for high voltage potentiometer * @param[in] tempdrift_pot_hv_high High threshold for high voltage potentiometer * @param[in] tempdrift_pot_amp_low Low threshold for amplifier potentiometer * @param[in] tempdrift_pot_amp_high High threshold for amplifier potentiometer * @param[in] tempdrift_pot_det_low Low threshold for detector potentiometer * @param[in] tempdrift_pot_det_high High threshold for detector potentiometer */ #define CMD_SET_TEMP_DRIFT_COMPENSATION_RANGES 0x7D04 typedef struct protocol_set_temp_drift_compensation_ranges_command_t { uint8_t tempdrift_pot_hv_low; uint8_t tempdrift_pot_hv_high; uint8_t tempdrift_pot_amp_low; uint8_t tempdrift_pot_amp_high; uint8_t tempdrift_pot_det_low; uint8_t tempdrift_pot_det_high; } __attribute__((packed)) protocol_set_temp_drift_compensation_ranges_command_t; void handle_set_flags_command(void *payload, uint16_t length); /* * @brief Get telemetry command and response structure * @param[out] hv_temp_c High voltage component temperature in 0.1°C * @param[out] amp_temp_c Amplifier component temperature in 0.1°C * @param[out] det_temp_c Detector component temperature in 0.1°C * @param[out] mcu_temp_c MCU temperature in 0.1°C * @param[out] vbias_mv SiPM bias voltage in mV * @param[out] hv_pot Current high voltage potentiometer setting * @param[out] amp_pot Current amplifier potentiometer setting * @param[out] det_pot Current detector potentiometer setting * @param[out] cps Current counts per second (CPM/60) * @param[out] cp10s Counts in the last 10 seconds * @param[out] total_counts Total counts since last reset */ #define CMD_GET_TELEMETRY 0x7400 typedef struct protocol_get_telemetry_response_t { uint16_t hv_temp_c; uint16_t amp_temp_c; uint16_t det_temp_c; uint16_t mcu_temp_c; uint16_t vbias_mv; uint8_t hv_pot; uint8_t amp_pot; uint8_t det_pot; uint16_t cps; uint32_t cp10s; uint32_t total_counts; } __attribute__((packed)) protocol_get_telemetry_response_t; void handle_get_telemetry_command(void *payload, uint16_t length); /* * @brief Flush counters command * @details Resets total counts and 10-second counts to zero */ #define CMD_FLUSH_COUNTERS 0x7401 void handle_flush_counters_command(void *payload, uint16_t length); /* * @brief Flush spectrum command * @details Clears all channel data and resets total counts to zero */ #define CMD_FLUSH_SPECTRUM 0x7402 void handle_flush_spectrum_command(void *payload, uint16_t length); /* * @brief Turn on the spectrometer circutry and enable fast ADC mode for radiation detection */ #define CMD_RSENSE_ENABLE 0x7500 void handle_rsense_enable_command(void *payload, uint16_t length); /* * @brief Turn off the spectrometer circutry and disable fast ADC mode for radiation detection */ #define CMD_RSENSE_DISABLE 0x7501 void handle_rsense_disable_command(void *payload, uint16_t length); /* * @brief Freeze spectrum data for reading */ #define CMD_SPECTRUM_FREEZE 0x7502 void handle_spectrum_freeze_command(void *payload, uint16_t length); /* * @brief Unfreeze spectrum data after reading */ #define CMD_SPECTRUM_UNFREEZE 0x7503 void handle_spectrum_unfreeze_command(void *payload, uint16_t length); /* * @brief Get counts since last request */ #define CMD_GET_COUNTS 0x7504 typedef struct protocol_get_counts_response_t { uint32_t counts; } __attribute__((packed)) protocol_get_counts_response_t; void handle_get_counts_command(void *payload, uint16_t length); /* * @brief Read spectrum data (arbitrary chunking for large data) */ #define CMD_READ_SPECTRUM_DATA 0x7505 typedef struct protocol_read_spectrum_chunk_command_t { uint16_t offset; uint16_t length; } __attribute__((packed)) protocol_read_spectrum_chunk_command_t; typedef struct protocol_read_spectrum_chunk_response_t { uint16_t offset; uint16_t length; // Followed by 'length' bytes of spectrum data } __attribute__((packed)) protocol_read_spectrum_chunk_response_t; void handle_read_spectrum_chunk_command(void *payload, uint16_t length); #endif /* PROTOCOL_H */