firmware/edu16_sbc
1
Fork 0
Code Issues Pull requests Projects Releases Activity

Freeze

Browse source
This commit is contained in:
ThePetrovich 2026-05-07 23:21:11 +08:00
parent 70798b6bf7
commit 3e77d34ccc
10 changed files with 669 additions and 146 deletions
Download patch file Download diff file Expand all files Collapse all files

308
sbc_fw/protocol.h Normal file
View file

@ -0,0 +1,308 @@
/*
* @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 <stdint.h>
/*
* @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 */