Skip to content

Commit cc48cca

Browse files
gab-kgab-k
committed
Update documentation doxygen comments
1 parent 185c703 commit cc48cca

File tree

5 files changed

+540
-337
lines changed

5 files changed

+540
-337
lines changed

‎Software/core0.h‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,22 +9,74 @@
99
#include "shared.h"
1010
#include "CV.h"
1111

12+
/**
13+
* @def MESSAGE_3_BYTES
14+
* @brief Comparison bitmask for detecting 3 byte long DCC messages/packets
15+
*/
1216
#define MESSAGE_3_BYTES 0b11111111110000000000000000000000000001
17+
/**
18+
* @def MESSAGE_MASK_3_BYTES
19+
* @brief Bitmask for detecting 3 byte long DCC messages/packets, input_bit_buffer is bitwise ANDed with the mask
20+
*/
1321
#define MESSAGE_MASK_3_BYTES 0b11111111111000000001000000001000000001
22+
/**
23+
* @def MESSAGE_4_BYTES
24+
* @brief Comparison bitmask for detecting 4 byte long DCC messages/packets
25+
*/
1426
#define MESSAGE_4_BYTES 0b11111111110000000000000000000000000000000000001
27+
/**
28+
* @def MESSAGE_MASK_4_BYTES
29+
* @brief Bitmask for detecting 4 byte long DCC messages/packets, input_bit_buffer is bitwise ANDed with the mask
30+
*/
1531
#define MESSAGE_MASK_4_BYTES 0b11111111111000000001000000001000000001000000001
32+
/**
33+
* @def MESSAGE_5_BYTES
34+
* @brief Comparison bitmask for detecting 5 byte long DCC messages/packets
35+
*/
1636
#define MESSAGE_5_BYTES 0b11111111110000000000000000000000000000000000000000000001
37+
/**
38+
* @def MESSAGE_MASK_5_BYTES
39+
* @brief Bitmask for detecting 5 byte long DCC messages/packets, input_bit_buffer is bitwise ANDed with the mask
40+
*/
1741
#define MESSAGE_MASK_5_BYTES 0b11111111111000000001000000001000000001000000001000000001
1842

43+
/**
44+
* @def INVALID_PACKAGE
45+
* @brief Return value of detect_dcc_packet() when the packet is invalid, meaning no packet was detected
46+
*/
1947
#define INVALID_PACKAGE SIZE_MAX
2048

49+
/**
50+
* @def RING_BUFFER_PACKETS
51+
* @brief First dimension of dcc ring buffer array - meaning RING_BUFFER_PACKETS can be retained inside the buffer
52+
*/
2153
#define RING_BUFFER_PACKETS 8
54+
/**
55+
* @def RING_BUFFER_BYTES
56+
* @brief Secoond dimension of dcc ring buffer array - meaning each packet can have a maximum size of RING_BUFFER_BYTES
57+
*/
2258
#define RING_BUFFER_BYTES 5
2359

60+
/**
61+
* @def FLASH_CMD_READ_JEDEC_ID
62+
* @brief Constant value of 0x9F used as a JEDEC ID read command for reading the JEDEC ID of a winbond flash memory chip
63+
*/
2464
#define FLASH_CMD_READ_JEDEC_ID 0x9F
65+
/**
66+
* @def FLASH_TIMEOUT_IN_MS
67+
* @brief Timeout value for flash access
68+
*/
2569
#define FLASH_TIMEOUT_IN_MS 500
2670

71+
/**
72+
* @def ADC_CALIBRATION_ITERATIONS
73+
* @brief Iterations for measuring adc offset
74+
*/
2775
#define ADC_CALIBRATION_ITERATIONS 8192
76+
/**
77+
* @def WATCHDOG_TIMER_IN_MS
78+
* @brief Watchdog timer setting, watchdog update needs to be called every WATCHDOG_TIMER_IN_MS milliseconds, otherwise decoder resets itself.
79+
*/
2880
#define WATCHDOG_TIMER_IN_MS 5000
2981

3082
/*!
@@ -53,6 +105,7 @@ const uint32_t clr_bit_arr[6] = {
53105
*
54106
* This structure is used to store the data and length of a DCC packet.
55107
*
108+
* @typedef dcc_packet_t
56109
* @struct dcc_packet_t
57110
*
58111
* @param data An array of bytes representing the DCC packet data.
@@ -71,6 +124,7 @@ typedef struct dcc_packet_t {
71124
* This structure is used to manage a ring buffer that stores DCC packets.
72125
* It contains an array of packets and indices for writing and reading.
73126
*
127+
* @typedef dcc_ring_buffer_t
74128
* @struct dcc_ring_buffer_t
75129
*/
76130
typedef struct dcc_ring_buffer_t {

‎Software/core1.h‎

Lines changed: 89 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -8,78 +8,107 @@
88
#pragma once
99
#include "shared.h"
1010

11+
12+
/**
13+
* @def BASE_PWM_ARR_LEN
14+
* @brief The length of the base PWM array.
15+
*
16+
* This macro defines the length of the base PWM ring buffer array.
17+
*/
1118
#define BASE_PWM_ARR_LEN 16
1219

20+
/**
21+
* @brief Enumeration for controller operating modes.
22+
*
23+
* Defines the two controller operating modes.
24+
*
25+
* @enum controller_mode_t
26+
*/
1327
typedef enum {
14-
STARTUP_MODE,
15-
PID_MODE,
28+
STARTUP_MODE, /**< Controller startup mode state */
29+
PID_MODE, /**< Controller pid mode state */
1630
} controller_mode_t;
1731

32+
/**
33+
* @brief Structure for startup controller parameters and variables.
34+
*
35+
* This structure defines the parameters and variables used in the startup
36+
* controller, including the latest PWM level, base pwm level ring buffer array and the respective ring buffer index.
37+
*
38+
* @typedef startup_parameters_t
39+
* @struct startup_parameters_t
40+
*/
1841
typedef struct startup_parameters_t {
19-
uint16_t level;
20-
uint16_t base_pwm_arr[BASE_PWM_ARR_LEN];
21-
uint16_t base_pwm_arr_i;
42+
uint16_t level; /**< Latest level */
43+
uint16_t base_pwm_arr[BASE_PWM_ARR_LEN]; /**< base pwm ring buffer array */
44+
uint16_t base_pwm_arr_i; /**< base pwm ring buffer array index */
2245
}startup_parameters_t;
2346

47+
/**
48+
* @brief Structure for PID controller parameters and variables.
49+
*
50+
* This structure defines the parameters and variables used in the PID
51+
* controller, including gains, error tracking, integrator limits, ...
52+
*
53+
* @typedef pid_parameters_t
54+
* @struct pid_parameters_t
55+
*/
2456
typedef struct pid_parameters_t{
2557
// PID Controller variables
26-
float k_i; // Integral gain
27-
float k_d; // Derivative gain
28-
float t; // Sampling time
29-
float tau; // Low-pass-filter time constant
30-
float ci_0; // (k_i*t)/2
31-
float cd_0; // (k_d*2)/(2*tau+t)
32-
float cd_1; // (2*tau-t)/(2*tau+t)
33-
float int_lim_max; // max limit for integrator
34-
float int_lim_min; // min limit for integrator
35-
float max_output; // max possible pwm output value
36-
float k_p; // Proportional gain
37-
float e; // Error
38-
float e_prev; // Previous Error
39-
float i_prev; // Previous Integral Value
40-
float d_prev; // Previous Derivative Value
41-
// Variable gain variables
42-
float k_p_x_1_shift;
43-
float k_p_x_1;
44-
float k_p_x_2;
45-
float k_p_y_0;
46-
float k_p_y_1;
47-
float k_p_y_2;
48-
float k_p_m_1;
49-
float k_p_m_2;
50-
} pid_parameter_t;
58+
float k_i; /**< Integral gain */
59+
float k_d; /**< Derivative gain */
60+
float t; /**< Sampling time */
61+
float tau; /**< Low-pass-filter time constant */
62+
float ci_0; /**< (k_i*t)/2 */
63+
float cd_0; /**< (k_d*2)/(2*tau+t) */
64+
float cd_1; /**< (2*tau-t)/(2*tau+t) */
65+
float int_lim_max; /**< max limit for integrator */
66+
float int_lim_min; /**< min limit for integrator */
67+
float max_output; /**< max possible pwm output value */
68+
float k_p; /**< Proportional gain */
69+
float e; /**< Error */
70+
float e_prev; /**< Previous Error */
71+
float i_prev; /**< Previous Integral Value */
72+
float d_prev; /**< Previous Derivative Value */
73+
// Variable gain variables - See gain scheduling documentation for more details
74+
float k_p_x_1_shift; /**< Effectively defines where x1 is shifted from 0% of max setpoint to 100% of max setpoint */
75+
float k_p_x_1; /**< x1 */
76+
float k_p_x_2; /**< x2 */
77+
float k_p_y_0; /**< y0 = KP @ x0 */
78+
float k_p_y_1; /**< y1 = KP @ x1 */
79+
float k_p_y_2; /**< y2 = KP @ x2 */
80+
float k_p_m_1; /**< slope from (x0, y0) to (x1, y1) */
81+
float k_p_m_2; /**< slope from (x1, y1) to (x2, y2) */
82+
} pid_parameters_t;
5183

84+
/**
85+
* @brief Structure for various controller parameters.
86+
*
87+
* This structure defines the highest level general controller parameters, including
88+
* General settings (setpoint, mode), startup controller settings struct, PID controller struct, and measurement data.
89+
*
90+
* @typedef controller_parameter_t
91+
* @struct controller_parameter_t
92+
*/
5293
typedef struct controller_parameter_t{
53-
/*!
54-
* General Variables
55-
*/
56-
controller_mode_t mode; // Controller mode
57-
float feed_fwd; // Feed forward value
58-
uint32_t setpoint; // Current setpoint
59-
uint16_t speed_table[127]; // Array with setpoint values corresponding to every speed step
60-
61-
/*!
62-
* Startup controller mode specific variables
63-
*/
64-
startup_parameters_t startup;
65-
66-
/*!
67-
* PID Controller variables
68-
*/
69-
pid_parameter_t pid;
70-
71-
/*!
72-
* Measurement Variables
73-
*/
74-
float measurement; // Newest Measurement value
75-
float measurement_prev; // Previous Measurement
76-
float measurement_corrected; // measurement - adc_offset = measurement_corrected
77-
float adc_offset; // ADC offset value
78-
uint8_t msr_delay_in_us; // Delay before VEMF Measurement
79-
uint8_t msr_total_iterations; // Amount of samples
80-
uint8_t l_side_arr_cutoff; // Discarded samples (left side)
81-
uint8_t r_side_arr_cutoff; // Discarded samples (right side)
82-
94+
// General controller parameters
95+
controller_mode_t mode; /**< Current controller mode */
96+
float feed_fwd; /**< Current feed forward value set by startup controller */
97+
uint32_t setpoint; /**< Current setpoint */
98+
uint16_t speed_table[127]; /**< Array with setpoint values corresponding to every speed step */
99+
// Startup controller parameters
100+
startup_parameters_t startup; /**< Struct for startup controller specific variables */
101+
// PID controller parameters
102+
pid_parameters_t pid; /**< Struct for PID controller specific variables */
103+
// Measurement variables
104+
float measurement; /**< Latest measurement value */
105+
float measurement_prev; /**< Previous measurement value */
106+
float measurement_corrected; /**< Corrected measurement value (measurement - adc_offset = measurement_corrected) */
107+
float adc_offset; /**< ADC offset value */
108+
uint8_t msr_delay_in_us; /**< Delay before V_EMF is measured */
109+
uint8_t msr_total_iterations; /**< Amount of samples */
110+
uint8_t l_side_arr_cutoff; /**< Discarded outlier samples (left side) */
111+
uint8_t r_side_arr_cutoff; /**< Discarded outlier samples (right side) */
83112
} controller_parameter_t;
84113

85114

‎Software/shared.c‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ speed_step_t speed_step_target = SPEED_STEP_REVERSE_STOP;
1111
speed_step_t speed_step_target_prev = SPEED_STEP_REVERSE_STOP;
1212
bool cv_setup_check_done = false;
1313
bool flash_safe_execute_core_init_done = false;
14-
static error_t error_state = 0;
14+
error_t error_state = 0;
1515

1616
// Functions in shared.c are accessed by both cores
1717

0 commit comments

Comments
 (0)