Header files

core0.h

Used exclusively by core0

Defines

SIZE_BYTE_ARRAY
MESSAGE_3_BYTES
MESSAGE_MASK_3_BYTES
MESSAGE_4_BYTES
MESSAGE_MASK_4_BYTES
MESSAGE_5_BYTES
MESSAGE_MASK_5_BYTES

Functions

float two_std_dev(const float arr[], uint32_t length)

Function returns average of values deviating less than twice the standard deviation from original average.

Parameters:
  • arr – input array

  • length – amount of elements in input array

Returns:

average value of values deviating less than 2*standard_dev.

void adc_offset_adjustment(uint32_t n)

Measures ADC offset and saves the offset value to flash memory.

Parameters:

n – Amount of measurements to be done

void acknowledge()

Function for acknowledging a CV write or CV verify instruction.

Acknowledgement works by creating a spike in current consumption, normally realized by running the motor in alternating directions. This current increase is detected by the command station. Refers to NMRA S-9.2.3 Section D and RCN-216 Section 3

void verify_cv_bit(uint16_t cv_address, bool bit_val, uint8_t bit_pos)

Function for verifying a single bit of a CV.

Parameters:
  • cv_address – CV Address

  • bit_val – Value of bit to be verified

  • bit_pos – Position of bit to be verified

void verify_cv_byte(uint16_t cv_address, uint8_t cv_data)

Function for verifying a CV byte.

Parameters:
  • cv_address – CV Address

  • cv_data – Byte to be verified

void write_cv_byte(uint16_t cv_address, uint8_t cv_data)

Function for writing a CV byte.

Parameters:
  • cv_address –

  • cv_data –

void program_mode(uint8_t number_of_bytes, const uint8_t byte_array[])

CV Programming mode function Used on entering programming mode in order to write CV values to persistent flash memory or verify/read bits/bytes from flash.

Refers to NMRA Standard 9.2.3 (“Service Mode Programming”) or RCN-216

Procedure:

  1. Checks for valid programming command

  2. Disables core1 timers

  3. Resets core1

  4. Saves interrupts

  5. Evaluates the type of programming instruction Write byte / Verify byte / Verify bit and runs corresponding function

  6. Restores interrupts

  7. Launch core1

Parameters:
  • number_of_bytes – Number of bytes in byte_array[]

  • byte_array – Pointer to byte_array[]

void set_outputs(uint32_t functions_to_set_bitmask)

Set outputs according to function mapping in CV257 to CV512.

This function maps the functions and direction to the mapped outputs configured in CV257 to CV512. Also enables PWM when enabled according to CV112 to CV115.

Parameters:

functions_to_set_bitmask – Function bitmask F0 is bit0, F1 is bit1, …

void update_active_functions(uint32_t new_function_bitmask, uint8_t clr_bit_ind, bool direction_change)
bool error_detection(int8_t number_of_bytes, const uint8_t *byte_array)
bool is_long_address(uint8_t number_of_bytes, const uint8_t byte_array[])
bool address_evaluation(uint8_t number_of_bytes, const uint8_t byte_array[])
void instruction_evaluation(uint8_t number_of_bytes, const uint8_t byte_array[])
bool reset_message_check(uint8_t number_of_bytes, const uint8_t *const byte_array)
int8_t verify_dcc_message()
void bits_to_byte_array(int8_t number_of_bytes, uint8_t byte_array[])
void evaluate_message()
void track_signal_rise(unsigned int gpio, long unsigned int events)

Track signal rising edge interrupt callback function.

Saves timer counter value using get_absolute_time(), then disables rising edge IRQ and enables falling edge IRQ. Parameters are unused.

Parameters:
  • gpio – Unused parameter

  • events – Unused parameter

void track_signal_fall(unsigned int gpio, long unsigned int events)

Track signal falling edge interrupt callback function.

Saves timer counter value using get_absolute_time(), then calculates time difference between rising and falling edge. When the time difference is greater than 87us, this bit is interpreted as a logical 0. Refers to NMRA S-9.1 and RCN-210 standards Puts the latest bit value into buffer, then evaluates complete buffer using evaluate_message(). Parameters are unused.

Parameters:
  • gpio – Unused parameter

  • events – Unused parameter

void init_outputs()

Output initialization function.

Initializes all allowed GPIO outputs as outputs

Sets PWM functionality for GPIOs configured as PWM pins CV_112 - CV_115 (see

CV.h

for reference)

PWM frequency and clock divider are configured according to CV_116 - CV_171 (see

CV.h for reference)

void cv_setup_check()

Checks various CV values in order to detect factory condition or pending calibrations.

Procedure:

  1. Check for flash memory factory condition when found write default values specified in CV.h to flash memory

  2. Check for existing ADC offset setup when not found write 7 to read-only CV_7 in order to trigger a ADC offset measurement/calibration

  3. Check for base PWM configuration/calibration, run calibration when none is found

void init_motor_pwm(uint8_t gpio)

Function initializes motor PWM for pin specified.

Parameters:

gpio – GPIO pin

void init_adc()

Initializes ADC.

Function initializes ADC, corresponding GPIO pins and ADC FIFO

Variables

const uint32_t clr_bit_arr[6] = {0b11111111111111111111111111100000, 0b11111111111111111111111000011111, 0b11111111111111111110000111111111, 0b11111111111000000001111111111111, 0b11100000000111111111111111111111, 0b00011111111111111111111111111111,}

Bitmasks used for clearing bits corresponding to function blocks.

[0] = F0-F4 [1] = F5-F8 [2] = F9-F12 [3] = F13-F20 [4] = F21-F28 [5] = F29-F31

core1.h

Used exclusively by core1

Defines

BASE_PWM_ARR_LEN

Typedefs

typedef struct startup_parameters_t startup_parameters_t
typedef struct pid_parameters_t pid_parameter_t
typedef struct controller_parameter_t controller_parameter_t

Enums

enum controller_mode_t

Values:

enumerator STARTUP_MODE
enumerator PID_MODE

Functions

uint8_t get_speed_step_table_index_of_speed_step(uint8_t speed_step)
bool speed_helper(struct repeating_timer *t)
void adjust_pwm_level(uint16_t level)
float get_kp(const controller_parameter_t *ctrl_par)
uint16_t get_initial_level(controller_parameter_t *ctrl_par)
void controller_startup_mode(controller_parameter_t *ctrl_par)
bool controller_general(struct repeating_timer *t)
void init_controller(controller_parameter_t *ctrl_par)
struct startup_parameters_t

Public Members

uint16_t level
uint16_t base_pwm_arr[BASE_PWM_ARR_LEN]
uint16_t base_pwm_arr_i
struct pid_parameters_t

Public Members

float k_i
float k_d
float t
float tau
float ci_0
float cd_0
float cd_1
float int_lim_max
float int_lim_min
float max_output
float k_p
float e
float e_prev
float i_prev
float d_prev
float k_p_x_1_shift
float k_p_x_1
float k_p_x_2
float k_p_y_0
float k_p_y_1
float k_p_y_2
float k_p_m_1
float k_p_m_2
struct controller_parameter_t

Public Members

controller_mode_t mode

General Variables

float feed_fwd
uint32_t setpoint
uint16_t speed_table[127]
startup_parameters_t startup

Startup controller mode specific variables

pid_parameter_t pid

PID Controller variables

float measurement

Measurement Variables

float measurement_prev
float measurement_corrected
float adc_offset
uint8_t msr_delay_in_us
uint8_t msr_total_iterations
uint8_t l_side_arr_cutoff
uint8_t r_side_arr_cutoff

shared.h

Used by both cores

Defines

LOGLEVEL
LOG(level, ...)
_125M
DCC_INPUT_PIN
MOTOR_FWD_PIN
MOTOR_REV_PIN
FWD_V_EMF_ADC_PIN
REV_V_EMF_ADC_PIN
GPIO_OUTPUT_PIN_MASK
GPIO_ILLEGAL_MASK
GPIO_ALLOWED_OUTPUTS
FLASH_TARGET_OFFSET

Functions

void core1_entry()
void write_cv_handler(uint16_t cv_index, uint8_t cv_data)
float measure(uint8_t total_iterations, uint8_t measurement_delay_us, uint8_t l_side_arr_cutoff, uint8_t r_side_arr_cutoff, bool direction)
uint32_t get_32bit_CV(uint16_t CV_start_index)
uint16_t get_16bit_CV(uint16_t CV_start_index)
bool get_direction_of_speed_step(uint8_t speed_step)

Calculates the direction based on a speed step byte.

This function calculates the direction of movement based on the value of the speed_step byte. It refers to the “128 Speed Control” standard as outlined in NMRA Standard 9.2.1 section 2.3.2.1 or RCN-212 section 2.2.2.

The following speed steps are defined:

DEC

BIN

DIRECTION

DEFINITION

000

0000 0000

Reverse

STOP

001

0000 0001

Reverse

EMERGENCY STOP

002

0000 0010

Reverse

Speed step 001

003

0000 0011

Reverse

Speed step 002

004

0000 0100

Reverse

Speed step 003

…

…. ….

Reverse

…

126

0111 1110

Reverse

Speed step 125

127

0111 1111

Reverse

Speed step 126

128

1000 0000

Forward

STOP

129

1000 0001

Forward

EMERGENCY STOP

130

1000 0010

Forward

Speed step 001

131

1000 0011

Forward

Speed step 002

132

1000 0100

Forward

Speed step 003

…

…. ….

Forward

…

254

1111 1110

Forward

Speed step 125

255

1111 1111

Forward

Speed step 126

Parameters:

speed_step – The speed step byte.

Returns:

true for forward direction, false for reverse direction.

Variables

repeating_timer_t pid_control_timer
repeating_timer_t speed_helper_timer
const uint8_t *CV_ARRAY_FLASH
uint8_t speed_step_target
uint8_t speed_step_target_prev

CV.h

Defines

CV_ARRAY_SIZE

Functions

uint8_t __in_flash ("Default_CV_values") CV_ARRAY_DEFAULT[CV_ARRAY_SIZE]