• Remote server functionality in probe-rs

  We have recently merged a series of exciting patches^{1 2 3 4} into probe-rs, that implement server-client functionality using websockets and postcard-rpc. In this post, I’ll try to explain the motivation behind the work, the design, configuration and usage of this feature.

  Why?

  I’ve been recently given the opportunity to try teleprobe. Teleprobe is the software that powers the embassy HIL test rig, and it gives a very convenient way to run a cargo project on an MCU that is connected to a remote machine. I was pretty impressed with the experience it gave me, and since teleprobe builds on top of probe-rs, I thought why shouldn’t we integrate a similar functionality into probe-rs itself?

  1. https://github.com/probe-rs/probe-rs/pull/3003 ↩

  2. https://github.com/probe-rs/probe-rs/pull/3049 ↩

  3. https://github.com/probe-rs/probe-rs/pull/3079 ↩

  4. https://github.com/probe-rs/probe-rs/pull/3081 ↩

• Debugging esp-hal, part 1 - The mysteriously hanging display drivers

  Preface

  This post is the first of (maybe hopefully, maybe not?) many writeups detailing esp-hal bugs and their fixes. Some of these are probably very obvious in hindsight, but maybe the story itself may be interesting. Or embarassing. Or full of learning opportunities. Regardless, journey before destination.

  A short while ago, one of our prominent community members sent me a project, with a short message that two of his display drivers don’t work on two separate ESP32 microcontrollers (ESP32, ESP32-S3), using two separate peripherals (I2S on the ESP32, LCD_CAM on the ESP32-S3), with esp-hal driver that implement the I8080 display format. That’s pretty weird because their respective drivers don’t have much code in common, but maybe this will be an easy case, and I can get two for one.

  Narrator: It was not.

• Coerce the compiler to help us debug Axum handlers

  Let’s state the obvious first: axum is good, it’s easy to use, it’s fast and all that. But have you ever seen an error like this?

  ❯ cargo c
      Checking axum-async v0.1.0 (C:\_Hobby\axum-async)
  error[E0277]: the trait bound `fn() -> impl Future<Output = ()> {page}: Handler<_, _>` is not satisfied
     --> src\main.rs:21:44
      |
  21  |     let app = Router::new().route("/", get(page));
      |                                        --- ^^^^ the trait `Handler<_, _>` is not implemented for `fn() -> impl Future<Output = ()> {page}`
      |                                        |
      |                                        required by a bound introduced by this call
      |
      = help: the trait `Handler<T, ReqBody>` is implemented for `Layered<S, T>`
  note: required by a bound in `axum::routing::get`
     --> C:\Users\bugad\.cargo\registry\src\github.com-1ecc6299db9ec823\axum-0.5.11\src\routing\method_routing.rs:396:1
      |
  396 | top_level_handler_fn!(get, GET);
      | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ required by this bound in `axum::routing::get`
      = note: this error originates in the macro `top_level_handler_fn` (in Nightly builds, run with -Z macro-backtrace for more info)
  
  For more information about this error, try `rustc --explain E0277`.
  error: could not compile `axum-async` due to previous error
  

  Rust is so good with its error messages that it’s just striking how very unhelpful this one is. Let’s see what we can do here!

• Announcing embedded-text 0.5.0

  A new stable version of embedded-text is available for download. embedded-text extends the excellent embedded-graphics library with a TextBox object that supports multiline text rendering with the common text alignment options, rich styling features and more!

  0.5.0 is a major update over the previous (0.4.x) iteration including new features, significant usability changes and bugfixes. 0.5.0 is also the first stable release built on top of embedded-graphics version 0.7.

  New features

  Plugins

  The new embedded-text now support plugins! Plugins are an experimental feature to extend the capabilities of the crate. To implement a plugin, users need to enable the plugins cargo feature.

  Note that imlementing a new plugin is experimental and the API may break without prior notice.

  The crate provides a small number of plugins that can be used without enabling the plugins feature.

  • Tail

    The Tail plugin can be used to keep the end of the text (the tail) in the displayed area. Example: in the left column, the text is top aligned. In the right column, the same text is displayed top-aligned, but with the Tail plugin active.

    

     use embedded_text::{
       plugin::tail::Tail, TextBox, ...
     };
    
     TextBox::new(...)
       .add_plugin(Tail) // < where the magic happens
       .draw(&mut display)?;
    

  • Ansi

    Enables text styling using (some) Ansi sequences. While this feature has been part of previous versions, now you can add it to select TextBox instances instead of enabling globally.

    

     use embedded_text::{
       plugin::ansi::Ansi, TextBox, ...
     };
        
     TextBox::new(...)
       .add_plugin(Ansi::new()) // < where the magic happens
       .draw(&mut display)?;
    

  Other, smaller features

  • Vertical text offsetting

    The vertical position of the text within a text box can now be modified using the vertical_offset text box option. Negative values move the text up, while positive values move it down.

    vertical_offset is a field of TextBox.

     use embedded_text::TextBox;
     ...
     let mut text_box = TextBox::new(...);
     text_box.vertical_offset = 10; // move text down by 10 pixels
    

  • Paragraph spacing

    The vertical distance between paragraphs (sections of text separated by a newline \n character) can now be changed using the paragrap_spacing style option.

     use embedded_text::style::TextBoxStyleBuilder;
     ...
     let textbox_style = TextBoxStyleBuilder::new()
       ...
       .paragraph_spacing(6)
       .build();
    

    In the following example picture, the paragraph spacing of the left text box is 0, while the right is 6.

    

  • Configurable space rendering

    You can now force to render or hide (collapse) the leading or trailing spaces in lines. This configuration does not change how the lines are measured and wrapped, it only affets what is rendered.

    Note that if a line is wrapped at a space (in case the space does not fit in the current line), a single space is consumed and will not be displayed or carried over to the next line.

    

  Usability changes

  These changes enable users to use embedded-text in a more flexible or simple way.

  TextBox configuration options are no longer encoded in the type of the text box object.

  Previously, style options like alignment were encoded in the type of the text box. This meant that storing the text box object in a variable (e.g. a struct field in an UI) was cumbersome and did not allow much flexibility.

  Starting with 0.5.0, embedded-text uses non-zero sized values (e.g. enums) as configuration, removing the old myriad of type parameters, making embedded-text easier to use and simpler to configure.

  New constructor functions

  To enable simpler construction of objects and to bring the API closer to embedded-graphics, this release adds new constructors to TextBox and TextBoxStyle. Use these functions if you only want to change a single property from the default style. These new constructors are:

  • TextBox::with_alignment / TextBoxStyle::with_alignment
  • TextBox::with_vertical_alignment / TextBoxStyle::with_vertical_alignment
  • TextBox::with_height_mode / TextBoxStyle::with_height_mode
  • TextBox::with_line_height / TextBoxStyle::with_line_height
  • TextBox::with_paragraph_spacing / TextBoxStyle::with_paragraph_spacing
  • TextBox::with_tab_size / TextBoxStyle::with_tab_size
  • TextBox::with_vertical_offset

  Removed

  This list is not exhaustive.

  • A substantial amount of the API (internal or not intended as public) has been hidden to reduce clutter.
  • TextBoxStyle objects can no longer be constructed (it is now #[non_exhaustive]).
  • Scrolling vertical alignment.
  • Ansi sequence support has been removed from the base library and reimplemented as the Ansi plugin.

  For a complete list of changes (excluding some under the hood changes), see the changelog.

  To install, add the following to your Cargo.toml dependencies:

  embedded-text = "0.5.0"
  

  For documentation, see docs.rs.

  I really hope you give embedded-text a try! If you have any questions, suggestions, issues, feature requests, or if you’d like to contribute, feel free to open an issue or a pull request on the GitHub repository!

• Announcing embedded-text 0.5.0-beta.4

  A new beta version of embedded-text is available for download. embedded-text extends the excellent embedded-graphics library with a TextBox object that supports multiline text rendering with the common horizontal alignment options and rich styling features.

  0.5.0-beta.4 is a minor update which includes a bunch of bug fixes and two new style properties to control leading and trailing space rendering, which might be interesting for certain plugins, or when rendering text with background color.

  For a complete list of changes (excluding some under the hood changes), see the changelog.

  To install, add the following to your Cargo.toml dependencies:

  embedded-text = "0.5.0-beta.4"
  

  For documentation, see docs.rs.

  I really hope you give embedded-text a try! If you have any questions, suggestions, issues, feature requests, or if you’d like to contribute, feel free to open an issue or a pull request on the GitHub repository!

• Announcing embedded-text 0.5.0-beta.3

  A new beta version of embedded-text is available for download. embedded-text extends the excellent embedded-graphics library with a TextBox object that supports multiline text rendering with the common horizontal alignment options and rich styling features.

  0.5.0-beta.3 includes refinements to the plugin system, as well as stable plugins that can be used without enabling the plugin feature.

  Stable plugins

  • Tail: The Tail plugin replaces the Scrolling vertical alignment. Use this to display the last lines of your text. The new plugin allows you to use initial (i.e. when the text fits the text box) vertical alignments other than Top.
  • Ansi: ANSI sequence support has been moved from the core of the library into the Ansi plugin. You can still disable the ansi feature if you want to reduce compile time by removing unused dependencies.

  To use a plugin, call the TextBox::add_plugin() method. Starting with beta.3, multiple plugins can be used at the same time.

  Note: Plugin support is currently experimental and unrefined. Expect breaking changes, or even complete removal in the future.

  For a complete list of changes (excluding some under the hood changes), see the changelog.

  To install, add the following to your Cargo.toml dependencies:

  embedded-text = "0.5.0-beta.3"
  

  For documentation, see docs.rs.

  I really hope you give embedded-text a try! If you have any questions, suggestions, issues, feature requests, or if you’d like to contribute, feel free to open an issue or a pull request on the GitHub repository!

• Announcing embedded-text 0.5.0-beta.2

  A new beta version of embedded-text is available for download. embedded-text extends the excellent embedded-graphics library with a TextBox object that supports multiline text rendering with the common horizontal alignment options and rich styling features.

  0.5.0-beta.2 includes the first preview of experimental plugin support! Gated behind the plugin cargo feature, this feature enables users to change how text is rendered. For simple examples, see the styles-plugin, interactive-editor and plugin examples.

  Note: Plugin support is currently experimental and unrefined. Expect breaking changes, or even complete removal in the future.

  For a complete list of changes (excluding some under the hood changes), see the changelog,

  To install, add the following to your Cargo.toml dependencies:

  embedded-text = "0.5.0-beta.2"
  

  For documentation, see docs.rs.

  I really hope you give embedded-text a try! If you have any questions, suggestions, issues, feature requests, or if you’d like to contribute, feel free to open an issue or a pull request on the GitHub repository!

• Announcing embedded-text 0.5.0-beta.1

  A new beta version of embedded-text is available for download. embedded-text extends the excellent embedded-graphics library with a TextBox object that supports multiline text rendering with the common horizontal alignment options and rich styling features.

  This release is a major step in the evolution of embedded-text. It targets the next generation of embedded-graphics. Over the last few months, an incredible amount of work has been done on text support in embedded-graphics and this work will be the foundation of some of the future changes in embedded-text.

  The new features of 0.5.0-beta.1 include:

  • embedded-text now uses embedded-graphics 0.7, which allowed removing several workarounds as well as simplifying the codebase.
  • The typestate-based configuration options have been replaced by enum values. This means embedded-text can be used in a more dynamic way than before.
  • Vertical text offset The rendered text can be moved vertically, enabling scrolling effects.
  • Paragraph spacing
  • Various updates to the API to make it similar to embedded-graphics’s Text API.

  For a complete list of changes (excluding some under the hood changes), see the changelog,

  To install, add the following to your Cargo.toml dependencies:

  embedded-text = "0.5.0-beta.1"
  

  For documentation, see docs.rs.

  I really hope you give embedded-text a try! If you have any questions, suggestions, issues, feature requests, or if you’d like to contribute, feel free to open an issue or a pull request on the GitHub repository!

• Announcing embedded-text 0.4.1

  A new stable version of embedded-text is available for download. embedded-text extends the excellent embedded-graphics library with a TextBox object that supports multiline text rendering with the common horizontal alignment options and rich styling features.

  This is a minor maintenance release that updates the ansi-parser dependency so that the ansi feature can now be used in no_std environments.

  To install, add the following to your Cargo.toml dependencies:

  embedded-text = "0.4.1"
  

  For documentation, see docs.rs.

  I really hope you give embedded-text a try! If you have any questions, suggestions, issues, feature requests, or if you’d like to contribute, feel free to open an issue or a pull request on the GitHub repository!

• Announcing embedded-text 0.4.0

  A new stable version of embedded-text (which is now part of the embedded-graphics organization 🎉) is available for download. embedded-text extends the excellent embedded-graphics library with a TextBox object that supports multiline text rendering with the common horizontal alignment options.

• Announcing embedded-text 0.3.0

  A new stable version of embedded-text is available for download. embedded-text extends the excellent embedded-graphics library with a TextBox object that supports multiline text rendering with the common horizontal alignment options.

• Announcing embedded-text 0.2.0

  A new stable version of embedded-text is available for download. embedded-text extends the excellent embedded-graphics library with a TextBox object that supports multiline text rendering with the common horizontal alignment options.

• Announcing embedded-text 0.1.0

  The first stable version of embedded-text is available for download. embedded-text extends the excellent embedded-graphics library with a TextBox object that supports multiline text rendering with the common horizontal alignment options.

• Micro-optimization of the day: bit masks

  In an embedded environment, using bit masks is quite common. Getting the nth bit of a word isn’t particularly difficult, a bitshift and a binary and does the trick:

  pub fn bit_n(bit: u32) -> u32 {
      1 << bit % 32
  }
  

  Nice and simple. Sometimes, however, we need to get a bit from the other end. To do this, we have two possibilities:

  • get the width - nth bit using something like above
  • construct our pattern some different way, i.e. by right shifting the leftmost bit

  pub fn left_bit_n_1(bit: u32) -> u32 {
      1 << 31 - bit % 32
  }
  
  pub fn left_bit_n_2(bit: u32) -> u32 {
      0x8000_0000 >> bit % 32
  }
  

  What can we tell about their performance?

• Announcing embedded-text 0.0.3

  A new test version of embedded-text is available for download. This version contains a few new features, a lot of internal improvements and fixes identified issues.

• Announcing embedded-text 0.0.1

  The first test version of embedded-text is available for download. embedded-text implements a TextBox struct with similar API as embedded-graphics Text, supporting multiline text rendering in a bounding box. embedded-text supports the common horizontal text alignment options:

  • LeftAligned
  • RightAligned
  • CenterAligned
  • Justified

  To install, add the following to your Cargo.toml dependencies:

  embedded-text = "0.0.1"
  

• Announcing embedded-layout 0.1.0

  The first stable version of embedded-layout is available for download. embedded-layout extends embedded-graphics with tools to align objects to each other and make it easier to compose complex screen layouts more easily.

  To install, add the following to your Cargo.toml dependencies:

  embedded-layout = "0.1.0"
  

• Extending embedded-graphics with simple layout functions

  The first version of embedded-layout is available for download. embedded-layout aims at making embedded-graphics easier to use, by allowing users to align elements to each other.

• Improving embedded-graphics' draw performance

  I’m always looking for ways to squeeze the most performance out of particularly hot code. Embedded-graphics and the SSD1306 driver gives some opportunity to do this, while also allowing me to extend e-g with a feature I need.

• How to fix ADS129x RLD output being stuck at AVDD

  I wanted to use my ADS1291’s Right Leg Drive amplifier to output the internal midsupply. I’ve spent several hours trying to figure out why it was stuck at AVDD. Spoiler alert: my configuration was incorrect.