stm32cubeprogrammer 0.1.0

Rust bindings for the STM32CubeProgrammer API
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119

//! This crate provides a high-level rust API for the STM32CubeProgrammer DLL.
//!
//! # Example usage:
//! ```no_run
//! use stm32cubeprogrammer::{
//!     probe::{ConnectionParameters, Protocol, ResetMode},
//!     CubeProgrammer, CoreRegister
//! };
//!
//! // You need to supply the path to the root directory of the STM32CubeProgrammer installation
//! let programmer = CubeProgrammer::builder()
//!     .cube_programmer_dir(
//!         &"C:\\Program Files\\STMicroelectronics\\STM32Cube\\STM32CubeProgrammer",
//!     )
//!     .build()
//!     .expect("Failed to create CubeProgrammer");
//!
//! let probes = programmer
//!     .list_available_probes()
//!     .expect("Failed to list available probes");
//!
//! probes.iter().for_each(|probe| {
//!     println!("{:?}", probe);
//! });
//!
//! let connected = programmer
//!     .connect_to_target(&probes[0], &Protocol::Swd, &ConnectionParameters::default())
//!     .expect("Failed to connect to target");
//!
//! println!("Target information: {}", connected.general_information());
//!
//! // Write and read core register R0
//! let value = 0x12345678;
//! connected
//!     .write_core_register(CoreRegister::R0, value)
//!     .expect("Failed to write core register");
//! let r0 = connected
//!     .read_core_register(CoreRegister::R0)
//!     .expect("Failed to read core register");
//! println!("R0: 0x{:08X}", r0);
//!
//! // If there are multiple connected probes with a target, you can establish multiple connections simultaneously
//! let connected_other = programmer
//!     .connect_to_target(&probes[1], &Protocol::Swd, &ConnectionParameters::default())
//!     .expect("Failed to connect to target");
//!
//! println!("Other target information: {}", connected_other.general_information());
//!
//! connected
//!     .reset_target(ResetMode::Hardware)
//!     .expect("Failed to reset target");
//!
//! // Drop also handles the disconnect, but you can also disconnect explicitly
//! connected.disconnect();
//!
//! // To update the BLE stack of a stm32wb55xx, you need to connect to the FUS
//! let connected = programmer
//!     .connect_to_target_fus(&probes[0], &Protocol::Swd)
//!     .expect("Failed to connect to FUS. Is the target a stm32wb55xx?");
//!
//! println!("FUS information: {}", connected.fus_info());
//! ```
//! More examples can be found in the `tests` directory.
//!
//! # Supported features:
//! - Downloading files as hex or bin
//! - Reading and writing memory
//!     - Uses the [`bytemuck::Pod`](https://docs.rs/bytemuck/1.21.0/bytemuck/trait.Pod.html) trait for reading and writing data from/to memory
//! - Reading and writing of core registers
//! - Resetting the target
//! - Enabling and disabling readout protection (Level B)
//! - Reset target
//! - Mass erase
//! - FUS operations (only for stm32wb55xx)
//! - Log messages of the CubeProgrammer DLL are forwarded via the [`display::DisplayCallback`] trait
//!
//! If there is a feature missing, feel free to open an issue or a pull request. :smile:
//!
//! # Running the tests
//! The tests require a STM32CubeProgrammer installation on the host machine and a connected st-link probe with a target.
//! To run the tests add a `.env` which at least contains the path to the STM32CubeProgrammer installation directory:
//! ```env
//! STM32_CUBE_PROGRAMMER_DIR="C:\\Program Files\\STMicroelectronics\\STM32Cube\\STM32CubeProgrammer"
//! ```
//! A list of the expected environment variables can be found in the `test_common.rs` file.
//!
//! # Other crates similar to this one
//! When I was looking for a rust API for the STM32CubeProgrammer DLL, I found [this](https://github.com/wervin/stm32cubeprog-rs) crate.
//! Playing around with it, I got interested in the topic and decided to try writing my own version. :rocket:
//!
//! # Requirements
//! There needs to be a Stm32CubeProgrammer installation on your system. The crates are tested using Stm32CubeProgrammer version 2.18.0.
//!
//! # Platform support
//! Windows and Linux are supported and tested.
//!
//! # Warranty
//! This crate is supplied as is without any warranty. Use at your own risk.
pub mod api_log;
pub use api_log::{LogMessageType, Verbosity};

pub mod api_types;
pub use api_types::{fus, probe, CoreRegister, GeneralInformation};

pub mod display;
pub use display::DisplayCallback;

pub mod cube_programmer;
pub use cube_programmer::{ConnectedFusProgrammer, ConnectedProgrammer, CubeProgrammer};

pub mod error;
pub mod utility;

// Re-export of the `bytemuck` crate -> needed for reading/writing of structs from/to memory
pub use bytemuck;

#[cfg(feature = "ihex")]
// Re-export of the `ihex` crate -> needed for parsing of Intel Hex files
pub use ihex;