esp-println

Provides print!, println! and dbg! implementations for various Espressif devices.

Supports ESP32, ESP32-C2/C3/C6, ESP32-H2, ESP32-S2/S3, and ESP8266
Dependency free (not even depending on esp-hal, one optional dependency is log, another is critical-section)
Supports JTAG-Serial output where available
Supports RTT (lacking working RTT hosts besides probe-rs for ESP32-C3)
no-op features turns printing into a no-op

RTT on ESP32-C3 / ESP32-C6

The cli utility should work for flashing and showing RTT logs on ESP32-C3 by using it's run command. You need to use the direct-boot feature of the HAL to flash via probe-rs.

Usage

In your Cargo.toml, under [dependencies], add:

esp-println = { version = "0.3.1", features = ["esp32"] }

Choose a recent version and your chipset.

Then in your program:

use esp_println::println;

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

Logging

With the feature log activated 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_LOGLEVEL sets the log level, use values like trace, info etc.
ESP_LOGTARGETS if set you should provide the crate names of crates (optionally with a path e.g. esp_wifi::compat::common) which should get logged, separated by , and no additional whitespace between

If this simple logger implementation isn't sufficient for your needs you can implement your own logger on top of esp-println - see https://docs.rs/log/0.4.17/log/#implementing-a-logger

defmt

Using the defmt 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 feature automatically uses the Rzcobs encoding and does not allow changing the encoding.

You can also use the defmt-raw feature that allows using any encoding provided by defmt, but does not add extra framing. Using this feature requires some care as the defmt output may become unrecoverably mangled when other data are printed.

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!

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.

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.

SergioGasquez/esp-println