Release v1.3.0

[npetersen2]

AMDC Firmware Release: v1.3.0

v1.3.0 has been released, making the default GitHub branch v1.3.x. Please see the changes below.

For users upgrading from v1.2.0 to the latest release, a comment has been left below on this page which details the steps needed to make your code compatible.

Changes in this release:

Timing Manager & Scheduler

• Create new Timing Manager IP to synchronize sensors and control with PWM carrier
• Convert scheduler times from uint32_t to double type, added tolerance margin

Sensor Interfaces

• Update sensor interfaces for Timing Manager compatibility
• Rename AMDS IP/driver from motherboard to amds
• Remove SYNC_TX interrupt from AMDS IP
• Add/change behavior of AMDS IP debug counters

FPGA Changes

• Remove FPGA Timer IP, as interrupts are now generated by Timing Manager
• Enable Inverter IP to flush duty ratios immediately, at next peak/valley, or next trigger
• Replace hardcoded AXI interface addresses with definitions from xparameters.h

Miscellaneous

• Convert any commands using 0-indexing for hardware port numbers to also be 1-indexed
• Remove obsolete driver documentation

Release Information

The main feature of release v1.3.0 is the updates made to timing and synchronization of key control events (sensor feedback and control task execution), particularly for high-speed research projects. This new timing synchronization is done via a new system-level FPGA peripheral, called the "Timing Manager". The Timing Manager synchronizes all sensor feedback and code execution to the peaks and valleys of the PWM switching carrier. Users can configure the timing manager to sample sensors and execute their code at an integer sub-rate of the PWM carrier.

This release also adds new control options to the Inverter/PowerStack interface. Users can configure newly-calculated duty ratios to be flushed out immediately, at the next PWM carrier peak/valley (as done in v.1.2.0), or at the next Timing Manager trigger event (recommended). Also added is the ability to enable/disable or invert the gate drive signals to each individual half-bridge.

Finally, GPIO port number indexing has been standardized to start at 1 across hardware REV D, E, and F, in both the C driver and command interface.

Contributors

Thanks to the following contributors in this release:

• @annikaolson
• @codecubepi
• @npetersen2

---

This discussion was created from the release v1.3.0.

[codecubepi]

Upgrading from v1.2.0

Due to significant system-level changes, existing users of v1.2.0 firmware may need to make modifications to their code to make it compatible with the new release. It is highly recommend that you commit your code to Git before following the steps below, so that your existing working code is recoverable!

1. Checkout the v1.3.0 release in git using SourceTree, or with the command line: git checkout v1.3.x

2. Open Vivado, re-generate the bitstream, and export the new hardware definition (File > Export > Export Hardware). The export location should be your workspace's AMDC-Hardware/sdk/ sub-folder.

3. Open the Xilinx SDK, and confirm in the pop-up that you would like to use the new hardware defintion. Re-build the entire workspace. You will likely encounter errors, as some system-layer definitions and function names have changed,

4. v1.3.0 introduces a new core piece of the AMDC system layer, called the Timing Manager. The Timing Manager synchronizes sensor feedback (analog, encoder, AMDS, and eddy current sensors) and control task execution to the PWM carrier. To configure the frequency at which the Timing Manager generates trigger events, you should add the following code to your control app's initialization function (app_name_init() in app_name.c):

// Timing Manager events occur when the PWM carrier is low (a valley).
// You can replace 'low' with 'high' or 'both' if needed.
timing_manager_trigger_on_pwm_low();

// Set the control task execution frequency by giving the Timing Manager a sub-rate ratio of the PWM Carrier Frequency
// i.e. If you are switching at 100 kHz and want sampling and control code to execute at 10 kHz (1/10 the PWM freq), set the Timing Manager ratio to 10
timing_manager_set_ratio(10);

5. Also in your app_name_init() function, you need to add functions that enable in the Timing Manager any sensors you use, as follows:

// Connect Eddy Current Sensor to GPIO Port 1 on REV D... you likely already have a similar line
gpio_mux_set_device(GPIO_MUX_BASE_ADDR, GPIO_MUX_DEVICE1)
// OR
// Connect Eddy Current Sensor to GPIO Port 1 on REV E/F... you likely already have a similar line
gp3io_mux_set_device(GP3IO_MUX_1_BASE_ADDR, GP3IO_MUX_DEVICE2)

// NEW: Enable Eddy Current Sensor connected to GPIO Port 1 in the Timing Manager (Any REV)
//      (You will have to add this function for each sensor interface you are using)
timing_manager_enable_sensor(EDDY_1);

6. If you are using the AMDS, the driver functions have changed names, and data sampling has been redirected through the Timing Manager. Any instances of motherboard_get_data() in your code should be renamed to amds_get_data(). If you call motherboard_set_adc_sampling() or motherboard_request_new_samples() anywhere in your code, these functions should be removed. All sampling is done by enabling the AMDS in the Timing Manager (as shown in Step 4).

7. If you are using the AMDS, you also need to update the firmware on your AMDS mainboard! That firmware is found here. You can checkout/pull the main branch of the AMDS repository to get the latest AMDS firmware. Open STM32CubeIDE, connect your AMDS to your PC using an ST-Link Debug Probe, and flash the latest firmware.

8. Finally, check over your user_config.h file. USER_CONFIG_ENABLE_MOTHERBOARD_SUPPORT has changed to USER_CONFIG_ENABLE_AMDS_SUPPORT. A new #define USER_CONFIG_ISR_SOURCE has been added to allow users to config when their control code is run. For backwards-compatibility, this #define defaults to 0, or "Legacy Mode", in which the Timing Manager will start sensor sampling and begin control code execution right at the PWM carrier peak/valley. However, to get the most out of the Timing Manager, the define should be changed to 1, or "New Mode". In this mode, the sensors will begin sampling at the carrier event, but control code execution will not begin until all enabled sensor interfaces have reported the latest data. If you are not using any sensors, mode 0 and mode 1 function exactly alike.

Further Support

If you have further questions, the following documentation created for this release may be useful:

• A tutorial covering Timing Manager and Sensor configuration is located here
• Detailed documentation on the Timing Manager is located here