Crate defmt_bbq

Source
Expand description

§defmt-bbq

A generic bbqueue based transport for defmt log messages

defmt (“de format”, short for “deferred formatting”) is a highly efficient logging framework that targets resource-constrained devices, like microcontrollers.

This crate stores the logged messages into a thread-safe FIFO queue, which can then be transferred across any medium, such as USB, RS-485, or other transports.

Although this crate acts as a global_logger implementer for defmt, it still requires you to do something with the messages. This is intended to be a reusable building block for a variety of different transport methods.

§Usage

This crates requires it’s users to perform the following actions:

  1. (optional): If you’d like to select a different queue size than the default 1024, you’ll need to set the DEFMT_BBQ_BUFFER_SIZE environment variable at build time to configure the size. e.g.: DEFMT_BBQ_BUFFER_SIZE=4096 cargo build.
  2. Prior to the first defmt log, the user MUST call defmt_bbq::init(), which will initialize the logging buffer, and return the Consumer half of the queue, which gives access to incoming logging messages
  3. The user must regularly drain the logged messages. If the queue is filled, any additional bytes will be discarded, potentially corrupting (some) logging messages

For more information on the Consumer interface, see the Consumer docs in the bbqueue crate documentation.

§Example

#[entry]
fn main() {
    // MUST be called before the first `defmt::*` call!
    let mut consumer = defmt_bbq::init().unwrap();

    loop {
        defmt::println!("Hello, world!");

        if let Some(grant) = consumer.read() {
            // do something with `bytes`, like send
            // it over a serial port..

            // Then when done, make sure you release the grant
            // to free the space for future logging.
            let glen = grant.len();
            grant.release(glen);
        }
    }
}

For a more detailed end-to-end example over USB Serial, please see the project’s example folder.

§Default Feature(s)

This crate has a single default feature, which enables the encoding-rzcobs feature of the defmt crate.

It is strongly recommended to leave this feature enabled (and to use rzcobs encoding) when using this crate. If the buffer is ever overfilled, then the remaining bytes will be discarded, which will temporarily corrupt the message stream.

Because rzcobs is delimited by zero bytes, it is possible to recover from this corruption, with the loss of a limited number of messages. When using the “raw” encoding, you MUST ensure that the buffer is never overfilled, as it will NOT be possible to recover from this error condition.

§Provenance

This repository is a fork of defmt-rtt, obtained from the defmt repository.

This repository was forked as of upstream commit 50e3db37d5429ed3344726f01e1bc4bf04902251.

§License

Licensed under either of

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 licensed as above, without any additional terms or conditions.

Structs§

  • Consumer
    This is the consumer type given to the user to drain the logging queue.
  • DefmtConsumer
    The consumer interface of defmt-log.
  • GrantR
    This is the Reader Grant type given to the user as a view of the logging queue.
  • SplitGrantR
    This is the Split Reader Grant type given to the user as a view of the logging queue.

Enums§

  • BBQError
    An error returned by the underlying bbqueue storage
  • Error
    The defmt-bbq error type

Constants§

  • BUF_SIZE
    BBQueue buffer size. Default: 1024; can be customized by setting the DEFMT_RTT_BUFFER_SIZE environment variable at compile time

Functions§

  • init
    Initialize the BBQueue based global defmt sink. MUST be called before the first defmt log, or it will latch a fault.