Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jamesmunns/defmt-bbq
A generic bbqueue based transport for defmt log messages
https://github.com/jamesmunns/defmt-bbq
Last synced: 11 days ago
JSON representation
A generic bbqueue based transport for defmt log messages
- Host: GitHub
- URL: https://github.com/jamesmunns/defmt-bbq
- Owner: jamesmunns
- License: apache-2.0
- Created: 2021-12-13T23:56:30.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2021-12-17T17:58:32.000Z (almost 3 years ago)
- Last Synced: 2024-10-09T07:10:13.204Z (30 days ago)
- Language: Rust
- Size: 28.3 KB
- Stars: 19
- Watchers: 5
- Forks: 5
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE-APACHE
Awesome Lists containing this project
README
# `defmt-bbq`
> A generic [`bbqueue`] based transport for [`defmt`] log messages
[`defmt`]: https://github.com/knurling-rs/defmt
[`bbqueue`]: https://github.com/jamesmunns/bbqueue
`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.
[Consumer docs]: https://docs.rs/bbqueue/latest/bbqueue/struct.Consumer.html
### Example
```rust
#[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](./examples/README.md).
## 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
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
http://www.apache.org/licenses/LICENSE-2.0)
- MIT license ([LICENSE-MIT](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
licensed as above, without any additional terms or conditions.