Crate esp_println

Crate esp_println 

Source
Expand description

§esp-println

Crates.io docs.rs MSRV Crates.io Matrix

A library that provides print!, println!, dbg! implementations and logging capabilities for Espressif devices.

  • Supports all Espressif ESP32 family devices.
  • Supports different communication methods:
    • UART
    • JTAG-Serial (Only available in ESP32-C3, ESP32-C6, ESP32-H2, ESP32-S3)
    • No-op: Turns printing into a no-op
  • Supports defmt backend

§Usage

esp-println = { version = "0.11.0", features = ["esp32c2"] }

or cargo add esp-println --features esp32c2 It’s important to specify your target device as feature.

Then in your program:

use esp_println::println;

You can now println!("Hello world") as usual.

§Logging

With the feature log-04 activated, and version 0.4 of the log crate added to your dependencies, you can initialize a simple logger like this:

init_logger(log::LevelFilter::Info);

There is a default feature colors which enables colored log output.

Additionally, you can use

init_logger_from_env();

In this case the following environment variables are used:

  • ESP_LOG log messages you want to show, similar to RUST_LOG. RegEx is not supported. e.g. warn,test::foo=info,test::foo::bar=debug

If this simple logger implementation isn’t sufficient for your needs, you can implement your own logger on top of esp-println. See Implementing a Logger section log documentaion

§defmt

Using the defmt-espflash feature, esp-println will install a defmt global logger. The logger will output to the same data stream as println!(), and adds framing bytes so it can be used even with other, non-defmt output. Using the defmt-espflash feature automatically uses the rzCOBS encoding and does not allow changing the encoding.

Follow the defmt book’s setup instructions on how to set up defmt. Remember, the global logger is already installed for you by esp-println!

Please note that defmt does not provide MSRV guarantees with releases, and as such we are not able to make any MSRV guarantees when this feature is enabled. For more information refer to the MSRV section of defmt’s README: https://github.com/knurling-rs/defmt?tab=readme-ov-file#msrv

§Troubleshooting linker errors

If you experience linker errors, make sure you have some reference to esp_println in your code. If you don’t use esp_println directly, you’ll need to add e.g. use esp_println as _; to your import statements. This ensures that the global logger will not be removed by the compiler.

§Minimum Supported Rust Version (MSRV)

This crate is guaranteed to compile when using the latest stable Rust version at the time of the crate’s release. It might compile with older versions, but that may change in any new release, including patches.

§License

Licensed under either of:

  • Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
  • MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

§Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

§Feature Flags

  • critical-section (enabled by default) — Use a critical section around print calls. This ensures that the output is consistent.

  • timestamp — Prints the timestamp in the log message.

    This option requires the following function to be implemented:

    extern "Rust" {
    fn _esp_println_timestamp() -> u64;
}

    This function should return the current timestamp in milliseconds since power on. When using esp_hal, you can define this function as follows:

    #[unsafe(no_mangle)]
pub extern "Rust" fn _esp_println_timestamp() -> u64 {
    esp_hal::time::Instant::now()
        .duration_since_epoch()
        .as_millis()
}

§Output interfaces

You must enable exactly 1 of the below features to enable to intended communication method.

Note: some boards, such as Waveshare’s ESP32-C6-DEV-KIT-N8, come with a USB hub. This can confuse the auto feature. If you experience no log output, try selecting an output interface instead of relying on auto.

  • auto (enabled by default) — Automatically select the best output interface for the target.
  • jtag-serial — Use the USB_SERIAL_JTAG interface for printing. Available on ESP32-C3, ESP32-C6, ESP32-H2, ESP32-P4, and ESP32-S3.
  • uart — Use the UART0 peripheral for printing. Available on all devices.
  • no-op — Don’t print anything

§Logging framework features

  • log-04 — Enables using the log crate for logging.

  • defmt-espflash — Enables printing using defmt.

    defmt-encoded output can only be read using espflash. With esp_hal, this works out of the box. Without esp_hal, you need to set the --log-format defmt argument for espflash.

§log-specific features

  • colors (enabled by default) — Colors the message severity in the terminal.

Modules§

defmt
defmt global logger implementation.

Macros§

dbg
Prints and returns the value of a given expression for quick and dirty debugging.
print
Prints to the selected output.
println
Prints to the selected output, with a newline.

Structs§

Printer
The printer that is used by the print! and println! macros.