blog.flxzt.net

pb-cheatsheet

2024-06-01T00:00:00+00:00

Dynamic Cheatsheets on Pocketbook E-Reader

2024-05-08T00:00:00+00:00

Motivation</h1>
My goal for this project was to repurpose my E-Reader device and write an application that dynamically displays cheatsheets based on the current focused window, acting as a special purpose second screen for mostly static content. The idea was to replace having to print cheatsheets and info cards for often used applications and tools like VSCode, Vim, Bash and so on.</p>
Pocketbook E-Reader devices are cool, because their firmware is Linux based and are, in comparison to other devices quite open. They allow creating custom applications in a standard linux environment and additionally Pocketbook's own SDK</a> for drawing directly on the display, retrieving input and interacting with their services and utilities.</p>
Unfortunately the publicly available SDK seems to not be regularly updated, but it still works on recent firmware. The actual used pocketbook E-Reader is the Touch Lux 3</a> (PB626) which is now already quite old but still works fine.</p>

Bindings</h2>
The language of choice to write software for me is Rust. The SDK</a> is written in C, so there is the need for bindings. Fortunately I am not treading on entirely new territory here. Ben Simms</a> already created inkview-rs</a>, a bindings crate that does bindings code generation through bindgen</a> and can be used in combination with cargo-zigbuild</a> to dynamically link the SDK with the built application.</p>
The bindings code is generated with bindgen's `--dynamic-loading</code> flag, so the actual symbols are linked at runtime through the dynamic linker ld</code>. No need to have a complicated build environment with a custom cross-compilation C toolchain for the SDK, linking .a</code> files, and so on!</p>`
`Because of that, remote development really is free of pain. Simply adding the armv7-unknown-linux-gnueabi</code> target to cargo and then executing cargo zigbuild --target armv7-unknown-linux-gnueabi.2.23</code> cross-compiles to armv7</code> with a specific glibc version that matches the one present on the Pocketbook device.</p>`

Rooting & SSH</h2>

By default it is not possible to run programs with root permissions on the device.
However, because the firmware uses an old kernel version that is vulnerable to the "Mad-COW" exploit
it is possible to "jailbreak" and install a root shell.
The pbjb</code> application has a guide in the "low-level-internals" section in the
mobileread forum thread</a> to do that.
After that programs with root permissions can be launched through /mnt/secure/su</code>.</p>
Now I could launch a SSH server with a script ssh-dropbear.app</code> that executes dropbear</code> like:</p>
#!/bin/sh
</span>/mnt/secure/su</span> /sbin/dropbear</span> -p</span> 2468</span> -G </span>""
</span></code></pre>
The installed dropbear version does not accept all key algorithms though,
I personally had trouble connecting at first.
After some research, I came up with this SSH config that should work in most cases:</p>
Host pocketbook
</span>  HostName <device-ip>
</span>  Port 2468
</span>  User root
</span>  HostKeyAlgorithms +ssh-rsa
</span>  PubKeyAcceptedAlgorithms +ssh-rsa
</span>  PubkeyAuthentication=no
</span>  StrictHostKeyChecking=no
</span></code></pre>
The SSH server should not be launched when the device is connected to non-trusted networks though
because anyone could connect to it as root without any authentication.</p>
App transfer</h2>
Applications with the file suffix .app</code> placed into the /mnt/ext1/applications</code> directory
(that appears as only applications</code> when the device is connected through USB)
are automatically shown in the applications launcher.
They can be binaries but also shell scripts.
This is very useful to create some tools to make the development easier.</p>
To iterate fast I wanted to be able to transfer the built application to the device
without any physical tasks like plugging a USB-cable in and out.</p>
To do that I utilized netcat</code>, a tool for creating ad-hoc network sockets and transmit arbitrary data over them.
The tool is already present on the device,
so I only needed to create scripts for the developer machine & device that send and receive applications.</p>


Sender:
echo </span>"Sending application name.."
</span>echo </span><</span>app-name</span>> | </span>nc </span><</span>device-ip</span>> </span>19991
</span># The e-reader needs a bit of time to re-launch 'nc'
</span>sleep</span> 3
</span>echo </span>"Sending application content.."
</span>nc </span><</span>device-ip</span>> </span>19991 </span><</span> /local/path/to/binary
</span></code></pre>
</div>

Receiver:
echo </span>"Listening for application name.."
</span>LOCAL_APP_NAME</span>=</span>$</span>(</span>nc</span> -l -p</span> 19991 </span>| </span>tr</span> -d </span>' '</span>)
</span>echo </span>"Received application name : '$</span>LOCAL_APP_NAME</span>'"
</span>LOCAL_APP_PATH</span>=</span>"/mnt/ext1/applications/$</span>LOCAL_APP_NAME</span>"
</span>echo </span>"Listening for application content.."
</span>nc</span> -l -p</span> 19991 </span>> </span>"$</span>LOCAL_APP_PATH</span>"
</span>echo </span>"Application has been saved to '$</span>LOCAL_APP_PATH</span>'"
</span></code></pre>
</div>
</div>
Debugging</h2>
I also wanted to debug remotely with gdb.
This is possible by: in a SSH session, launching a gdbserver</code> session with command
gdbserver 0.0.0.0:10003 /mnt/ext1/applications/<app-name>.app</code>.</p>
On the developer machine when using vscode for development,
the extension 'CodeLLDB' can be used for debugging Rust code.
A launch.json</code> configuration entry ended up looking like this:</p>
{
</span>    </span>"type"</span>: </span>"lldb"</span>,
</span>    </span>"request"</span>: </span>"custom"</span>,
</span>    </span>"name"</span>: </span>"remote debug <app-name>"</span>,
</span>    </span>"targetCreateCommands"</span>: </span>[
</span>        </span>"target create ${workspaceFolder}/target/armv7-unknown-linux-gnueabi/debug/examples/<app-name>"
</span>    ]</span>,
</span>    </span>"processCreateCommands"</span>: </span>[
</span>        </span>"gdb-remote <device-ip>:10003"
</span>    ]
</span>}
</span></code></pre>
Now I could step through code, set breakpoints and so on.
Of course it's also possible to use the gdb CLI directly.</p>
inkview-rs Improvements</h1>
The inkview-rs</code> bindings crate needed additional features and fixes to satisfy my needs.
For one, it needed to be extended to the SDK version v5.19</code> that is supported on the Touch Lux 3.
Previously, only bindings for v6.5</code> were generated.
These API versions can now be switched through cargo features sdk-5-19</code> and sdk-6-5</code> at compile time.</p>
I added additional safe rust wrappers for common tasks like a fast screen update and a wrapper for the dialog API.
The library also previously had issues with an vertical draw offset which could be fixed
by an setting a specific application flag through the pocketbook SDK.</p>
Additionally I added an adapter crate inkview-eg</code> which implements the
embedded_graphics::DrawTarget</a>
trait for the display.
Doing that enables drawing with convenient API for graphics primitives and even things like text and bitmap images.</p>
pb-cheatsheet Application</h1>
Overview</h2>
Establishing a solid development environment and improvements to the inkview-rs library took a few weeks
while working on-and-off on it.
But after that I could focus on the application itself.
The code is entirely open-source under 'GPLv3' and can be found here</a></p>
The host side is a CLI tool that is able to communicate with the GRPC server of the client.
It should have the following features:</p>

ability to upload cheatsheets (images) to the client</li>
register/delete associated tags</li>
retrieve device state</li>
ability to take screenshots and automatically upload them to the client</li>
continuously report the current focused window</li>
</ul>
The client is a pocketbook specific application that holds and manages state and draws to the screen.
For communication with the host it starts a GRPC server.
It should be possible to display some stats like the reported focused window by pressing the Menu</code> button.
There should also be three distinct modes as UI:</p>

Manual</code> : the user can manually cycle through the uploaded cheatsheets</li>
Automatic WM-Class</code> : display cheatsheets for which tags are registered that match with the tags
registered to the reported focused window class.</li>
Screenshot</code> : display the last uploaded screenshot</li>
</ul>
Now let's get into the details of how all of this is actually implemented.</p>
Host</h2>
CLI</h3>
The following commands are implemented:</p>
Usage: pb-cheatsheet-host --pb-grpc-addr <PB_GRPC_ADDR> <COMMAND>
</span>
</span>Commands:
</span>  report-focused-window   Continuously report focused window info to the client.
</span>                               Intended to be run as a service
</span>  get-screen-info         Get device screen info
</span>  get-cheatsheets-info    Get cheatsheets info
</span>  upload-cheatsheet       Upload a new cheatsheet that gets displayed when the added tags match the tags
</span>                               that are added to the wm class of the reported window.
</span>                               The image size is adjusted depending on the reported screen info of the client
</span>  remove-cheatsheet       Remove a cheatsheet
</span>  screenshot              Take a screenshot and upload it to the device for transient display
</span>  clear-screenshot        Clear the screenshot
</span>  add-cheatsheet-tags     Add cheatsheet tags
</span>  remove-cheatsheet-tags  Remove cheatsheet tags
</span>  add-wm-class-tags       Add wm class tags
</span>  remove-wm-class-tags    Remove wm class tags
</span>  help                    Print this message or the help of the given subcommand(s)
</span></code></pre>
For example the output when fetching cheatsheet info looks like this:</p>
</p>
Fetching Info</h3>
Retrieving the focused window is implemented only for the Gnome desktop environment,
because unfortunately there is no universal Wayland protocol yet
that would enable a desktop environment independent implementation.</p>
The Gnome extension focused-window-dbus</a> must also be
installed. It reports the focused window through a DBus interface.</p>
The host application uses zbus</a> to fetch this info from the extension.
The core Rust code to do that looks like this:</p>
#</span>[</span>proxy</span>(
</span>    default_service </span>= </span>"org.gnome.Shell"</span>,
</span>    default_path </span>= </span>"/org/gnome/shell/extensions/FocusedWindow"</span>,
</span>    interface </span>= </span>"org.gnome.shell.extensions.FocusedWindow"
</span>)]
</span>trait </span>FocusedWindow </span>{
</span>    async </span>fn </span>get</span>(</span>&</span>self</span>) </span>-> </span>Result</span><</span>String</span>></span>;
</span>}
</span>
</span>pub</span>(</span>crate</span>) async </span>fn </span>get_focused_window_info</span><</span>'a</span>>(
</span>    </span>connection</span>: </span>&</span>Connection,
</span>) </span>-> </span>anyhow</span>::</span>Result</span><FocusedWindowInfo> {
</span>    </span>let</span> proxy </span>= </span>FocusedWindowProxy</span>::</span>new(connection)</span>.</span>await</span>?</span>;
</span>    </span>let</span> val</span>: </span>serde_json</span>::</span>Value </span>= </span>serde_json</span>::</span>from_str(</span>&</span>proxy</span>.</span>get</span>()</span>.</span>await</span>?</span>)</span>?</span>;
</span>    </span>// ...
</span>}
</span></code></pre>
Service</h3>
The pb-cheatsheet-host report-focused-window</code> command continuously fetches info about the current focused window
and reports it to the client over GRPC when it changes.</p>
This command can be a service that is started by systemd. A suitable .service</code> file:</p>
[</span>Unit</span>]
</span>Description</span>=</span>"pb-cheatsheet-host focused window reporter"
</span>StartLimitIntervalSec</span>=</span>0
</span>StartLimitBurst</span>=</span>0
</span>
</span>[</span>Service</span>]
</span>Environment</span>=</span>"PB_GRPC_ADDR=<client-ip:51151>"
</span>Environment</span>=</span>"RUST_LOG=pb-cheatsheet-host=<log-level>"
</span>ExecStart</span>=</span>%h/.cargo/bin/pb-cheatsheet-host report-focused-window
</span>Restart</span>=</span>on-failure
</span>RestartSec</span>=</span>30
</span>
</span>[</span>Install</span>]
</span>WantedBy</span>=</span>default.target
</span></code></pre>
Client</h2>
The client starts a GRPC server listening to incoming procedure call requests and messages.</p>
It does that in an asynchronous task, which sends messages over a channel to the handler. This handler also receives
incoming messages from the pocketbook event main loop.
Because the pocketbook SDK is not designed to be used in an async context, both "worlds",
async and blocking, have to be combined carefully.</p>
The client also holds some state about the cheatsheets, their tags and the UI.</p>
Persistence</h3>
The cheatsheets and the metadata containing the tags are saved as files whenever changes are made
and when the app is closed.
The populated save directory looks like this:</p>
save_dir/
</span>  </span>wm_class_tags.json </span># JSON file containing the tags that are associated with windows
</span>  </span>cheatsheet_app_1.cs </span># Raw cheatsheet image data about <app1>
</span>  </span>cheatsheet_app_1.json </span># Metadata about <app1> cheatsheet containing associated tags
</span>  </span># ..
</span></code></pre>
The metadata is saved as json</code> with serde</a>
and serde_json</a>.</p>
For the cheatsheets images serde and bincode</a> is used for maximizing efficiency
for raw image data.
The images themselves are pre-converted to 8-bit grayscale and scaled the client display resolution on the host.</p>
Dynamic Cheatsheets using Tags</h3>
The tags system works like this:</p>
</a></p>
Every window class is associated with different tags grouping different cheatsheets.
For every tag that matches, the corresponding cheatsheet is displayed. The user is able to cycle through them
with the Prev</code>/Next</code> buttons.</p>
Screenshot feature</h3>

  
</video>
The host uses the XDG Desktop Screenshot Portal</a>
to open the screenshot tool and fetch the save path.
It then reads the image data from the path, prepares and sends it to the client.
The client then automatically switches to the Screenshot</code> UI mode and displays that image.
For users of dark mode UI's, there is the possibility to invert the screenshot colors with a flag.</p>
RPC</h2>
For communication and remote procedure calls between host and client GRPC</a> is used.
The protocol is specified in a protobuf .proto</code> file. A snippet:</p>
syntax </span>= </span>"proto3"</span>;
</span>package </span>pb_cheatsheet</span>;
</span>
</span>service </span>PbCheatsheet </span>{
</span>  </span>rpc </span>FocusedWindow</span>(FocusedWindowInfo) </span>returns </span>(Empty) {}
</span>  </span>rpc </span>GetScreenInfo</span>(Empty) </span>returns </span>(ScreenInfo) {}
</span>  </span>rpc </span>GetCheatsheetsInfo</span>(Empty) </span>returns </span>(CheatsheetsInfo) {}
</span>  </span>rpc </span>UploadCheatsheet</span>(UploadCheatsheetRequest) </span>returns </span>(Empty) {}
</span>  </span>// ...
</span>}
</span>
</span>// ...
</span></code></pre>
The tonic</a> crate generates Rust code for client and server out of it.</p>
Cheatsheets</h2>
To create cheatsheets easily there is a typst template
that is optimized for 'keyboard-key' -> 'functionality' pair lists,
uses an E-Paper suitable font and scales it's content for the lower resolution
while reducing margins to maximize available space.</p>
A snippet how this template is used for a git cheatsheet:</p>
#import "./cheat-template.typ": cheat
</span>
</span>#show: cheat.with(
</span>  title: [Git Cheatsheet],
</span>  icon: image("icons/git.svg"),
</span>)
</span>
</span>#table(
</span>  table.header[Adding changes],
</span>  [`git add -u <path>`], [Add all tracked files to the *staging area*.],
</span>  [`git add -p <path>`], [Interactively pick which files to *stage*],
</span>)
</span>
</span>// ..
</span></code></pre>
The rendered image looks like this:</p>
</a></p>
Conclusion</h1>
It was a lot of work, but I gained a lot of knowledge about creating a development environment and
the additional hurdles when developing for remote embedded linux systems.
Generating bindings that do dynamic linking and using 'zigbuild' stand out as very useful tools
to avoid most of the pain of that would come with a 'regular' cross-build setup.</p>
I also really enjoyed using GRPC as the remote procedure call mechanism between host and client.
It seems very efficient, well thought out with regards to forward and backwards compatibility, stable
and on top of it, was also quite easy and enjoyable to work with.
So it will be one of my first choices in future projects that need to do RPC.</p>
I think this turned out pretty well, I achieved basically all of the goals for features
that I had planned before I started.</p>



ink-stroke-modeler-rs
2024-03-01T00:00:00+00:00



Mercury
2023-06-01T00:00:00+00:00



wave
2023-03-01T00:00:00+00:00



Splot
2023-02-01T00:00:00+00:00



Motion & Gesture Recognition for low-res TOF-Sensors
2022-12-18T00:00:00+00:00
Motivation</h1>
Low-cost Time-Of-Flight sensors like the "ST VL53L5CX" usually have low resolution SPAD arrays (e.g. 4x4 or 8x8) with
individual zones, each measuring a distance to an object located in a section of the FOV of the sensor.
These measurement can be processed on a MCU like a STM32 to recognize motion and gestures. For this purpose I created a
no-std, no-alloc Rust library with C-bindings to be able to integrate it into C-based embedded codebases, such as the
ones created by STM32CubeMX.

This blog post explains the algorithms how this library calculates positions and recognizes motions and gestures from
the sensor values.</p>
Coordinates</h1>
First, let's establish how positions in relation to the sensor are represented as coordinates.</p>
$$
C_{cart} =
\begin{pmatrix}
x: \text{distance to origin on x-axis}\newline
y: \text{distance to origin on y-axis}\newline
z: \text{distance to origin on z-axis}\newline
\end{pmatrix}
$$</p>
$$
C_{spher} =
\begin{pmatrix}
r: \text{distance to the origin}\newline
\theta \text{ (theta): angle to x-axis (azimuth)}\newline
\phi \text{(phi): angle to y-axis (zenith)}\newline
\end{pmatrix}
$$</p>
</a></p>
This spherical notation is the mathematical convention.

(reference: mathworld.wolfram.com/SphericalCoordinates.html</a>)</p>
Conversion</h2>
Convert between the two: From spherical to cartesian coordinates
$$
\begin{align}
x &= r \cdot \cos(\theta) \cdot \sin(\phi)\newline
y &= r \cdot \sin(\theta) \cdot \sin(\phi)\newline
z &= r \cdot \cos(\phi)
\end{align}
$$</p>
and from cartesian to spherial
$$
\begin{align}
\textcolor{green}{r} &= \sqrt{x^2 + y^2 + z^2}\newline
\theta &= \arctan(y / x)\newline
\phi &= \arccos( z / \textcolor{green}{r} )
\end{align}
$$</p>
Sensor Grid</h1>

    
        </a>
    </div>
</aside>
We have for each zone:</p>
$$
\begin{align}
dist_{i_x, i_y} &: \text{the measured distance}\newline
i_x &: \text{horizontal index in the sensor grid}\newline
i_y &: \text{vertical index in the sensor grid}\newline
\end{align}
$$</p>
To determine the position of the measurement in each zone, we need to calculate it with the Sensor-FOV:</p>
$$
\begin{align}
Res_{hor} &: \text{horizontal resolution}\newline
Res_{vert} &: \text{vertical resolution}\newline
Fov_{hor} &: \text{horizontal sensor field-of-view}\newline
Fov_{vert} &: \text{vertical sensor field-of-view}
\end{align}
$$</p>
</div>
We can determine the zone angle deltas:</p>
$$
\begin{align}
a_{zone, hor} &= \frac{Fov_{hor}}{Res_{hor}}\newline
a_{zone, vert} &= \frac{Fov_{vert}}{Res_{vert}}\newline
\end{align}
$$
and then we can get the spherical coordinates:
$$
C_{spher, i_x, i_y} =
\begin{pmatrix}
\begin{align}
r &= dist_{i_x, i_y}\newline
\theta &= (i_x - \frac{Res_{hor}}{2}) \cdot a_{zone, hor}\newline
\phi &= \frac{\pi}{2} - (i_y - \frac{Res_{vert}}{2}) \cdot a_{zone, vert}\newline
\end{align}
\end{pmatrix}
$$</p>
Object Position</h1>
To determine the position of an object in front of the sensor relatively accurately even with the low resolution, we use
the following method:

We calculate the coordinates for all zones. Then we take the one with the smallest distance $r$ as the initial position
$C_{min}$. Because that alone is not very accurate, we need to weigh in the other measurements. We use the weighted
average mean:</p>
$$
C_{obj} =
\frac{
\sum_{i_x = 0, i_y = 0}^{n_x = Res_{hor}, n_y = Res_{vert}} \omega_{i_x, i_y} \cdot C_{i_x, i_y}
}{
\sum_{i_x = 0, i_y = 0}^{n_x = Res_{hor}, n_y = Res_{vert}} \omega_{i_x, i_y}
}
$$</p>
Now, how should this weight $\omega_{i_x, i_y}$ look like? Because the object is likely larger than the FOV of a single
zone, it should count in neighboring zones as well. The further away a measurement is to $ C_{min} $, the less it should
be weighted. With this criteria, we can construct a formula like this:</p>
$$
\omega_{i_x, i_y}(C_{min}, C_{i_x, i_y}) = f \cdot \frac{1}{| C_{min} - C_{i_x, i_y}|}
$$</p>
$f$ is a factor that determines how much the distance weighs in. This can be adjusted based on the size and distance of
the to be detected objects and is an entirely subjective value.</p>
Motion and Gesture Recognition</h1>
Now that we have determined the object position, we save it for every sensor readout in a vector, with the time when it
was measured. To be able to reliably recognize gestures, this vector should hold at least ca 2 seconds of position data,
so for a 15Hz sensor it should hold at least 30 elements, for a 60Hz sensor it should at least hold 120 elements. The
size of course also depends on the memory constraints of the device that runs the library.

To avoid accidental recognition of far away objects, detection can be aborted if the distances are above a certain
threshold.</p>
Swipes</h1>
To detect swipes, we look at the measurements newer than a specified time (ca 600ms) and look if the object position has
moved horizontally more than a certain distance. To make this more robust, we only recognize the gesture if the object
also has not moved much towards or away from the sensor.</p>
</a>


    The recognition of a swipe gesture
</span></p>
Static Holds</h1>
Static holds are determined when the object position has not changed above a distance threshold for a specified amount
of time.</p>
</a>


    The recognition of a hold gesture
</span></p>
Implementation</h1>
stay tuned for another post that shows the implementation as a no-std, no-alloc Rust library with integration into an
existing STM32 C-based project. It will also show how HID keyboard reports are sent when a gesture is recognized, and
how to debug the Rust library on an STM32-F4 MCU.</p>
The code (a STM32CubeIDE project) is already available here</a>.</p>


TinyUSB on STM32 MCU's with STM32CubeIDE
2022-08-28T00:00:00+00:00
When using the USB peripheral on STM32 MCU's, you can choose between the vendor-provided USB stack and a third-party
one like TinyUSB</a>. The vendor-provided is inconvenient to use because even though
it provides a selection of predefined classes, the code generation always overwrites any changes one might need to make
to the stack to customize it or even to fix bugs in the implementation.
TinyUSB has the advantage to be hardware-independent, is easy-to-use and highly customizable. Its disadvantage is that
its integration into STM32CubeIDE and the HAL is not straight-forward. Hence this guide.</p>
STMCubeMX configuration</h1>

    
        </a>
    </div>
</aside>
TinyUSB uses the abstractions of the lower-level HAL for STM32 MCU's. This is configured in CubeMX. First, the
USB_OTG_FS</code> peripheral in the Connectivity</code> section needs to be enabled. Set it to Device Only</code> and most importantly
check the global USB interrupt in NVIC Settings</code>. This generates the OTG_FS_IRQHandler()</code>  interrupt callback in the
stm32f<x>xx_it.c</code> file, it is needed later.</p>
Make sure that the USB Device</code> in Middleware</code> is not</strong> enabled.</p>
Then the clock solver needs to be run the  in Clock configuration</code>. After that work is done in the CubeMX tool and the
code can be generated.</p>
</div>STM32CubeIDE integration</h1>
First, the TinyUSB repository needs to be cloned into the project and enabled for linking and compilation.</p>
In the project root directory, execute:</p>
git</span> clone https://github.com/hathach/tinyusb
</span># Or when the repository itself is managed with git
</span>git</span> submodule add https://github.com/hathach/tinyusb
</span></code></pre>
TinyUSB itself uses some library submodules in lib</code>, which need to be initialized.</p>
cd</span> tinyusb
</span>git</span> submodule update</span> --init --recursive</span> lib
</span></code></pre>
It is recommended to use a released version, so the repository needs to be checked out to a release tag (0.14.0</code> at the
time of writing):</p>
git</span> fetch</span> --all --tags
</span>git</span> checkout 0.14.0
</span></code></pre>

    
        </a>
    </div>
</aside>
Then the linker and compiler need to be configured. First, open the projects properties window under
Project->Properties</code> and navigate to C/C++ Build->Settings</code>. In the MCU GCC Compiler->Include Paths</code> view you can add
the path to the TinyUSB source directory to include its header files.

Make sure it is added for all configurations.</p>
Then navigate to C/C++ General->Paths and Symbols</code> and in Source Location</code> add the TinyUSB source directory as well
for all configurations.</p>
</div>
At the time of writing with v0.14.0</code> there are two drivers for STM32 devices. Leaving them both enabled would result in
Symbol already defined</code> compilation errors. To prevent this, one of them needs to be disabled. This can be done by
excluding its file with a filter. Select the added path and click on Edit Filters</code> on the right side. Then add the
portable/st/synopsys/dcd_synopsys.c</code> to the filter.

This disables the older driver, and the newer driver in portable/synopsys/dwc2/dcd_dwc2.c</code> gets used. By
developer comment</a> the older one will be
removed at some point so this might not be necessary anymore in the future.</p>
</a></p>
Code (CDC dual ports example)</h1>
To be able to use TinyUSB, it needs to be integrated in the existing code.
For demonstration purposes the CDC dual ports example</a>
will get used.</p>
tusb_config.h</h2>
TinyUSB expects the tusb_config.h</code> configuration file to be present. In there the library and the peripheral is
configured. Create it in Core/Inc</code>.</p>
The CFG_TUSB_MCU</code> and CFG_TUSB_OS</code> definitions are mandatory. Valid values for both definitions can be looked up in
tusb_option.h</code>.</p>
// tusb_config.h
</span>
</span>// ...
</span>
</span>// Debugging
</span>#define </span>CFG_TUSB_DEBUG        </span>3
</span>
</span>// Enable device stack
</span>#define </span>CFG_TUD_ENABLED       </span>1
</span>
</span>// Endpoint size for full-speed
</span>#define </span>CFG_TUD_ENDPOINT0_SIZE    </span>64
</span>
</span>// Enables 2 interfaces of class CDC
</span>#define </span>CFG_TUD_CDC               </span>2
</span>
</span>// ...
</span></code></pre>
usb_descriptor.c</h2>
Add usb_descriptors.c</code> in Core/Src/</code>. This file is for configuring the USB descriptors.</p>
// usb_descriptor.c
</span>
</span>#include </span>"tusb.h"
</span>
</span>// ...
</span>
</span>#define </span>_PID_MAP</span>(</span>itf</span>, </span>n</span>)  ( (CFG_TUD_##itf) </span><< </span>(n) )
</span>#define </span>USB_PID           </span>(</span>0x4000 </span>| </span>_PID_MAP</span>(CDC</span>, </span>0</span>) </span>| </span>_PID_MAP</span>(MSC</span>, </span>1</span>) </span>| </span>_PID_MAP</span>(HID</span>, </span>2</span>) </span>|</span> \
</span>                           </span>_PID_MAP</span>(MIDI</span>, </span>3</span>) </span>| </span>_PID_MAP</span>(VENDOR</span>, </span>4</span>) )
</span>#define </span>USB_VID   </span>0xCafe
</span>#define </span>USB_BCD   </span>0x0200
</span>
</span>// ...
</span>
</span>uint8_t </span>const</span> desc_fs_configuration[] </span>=
</span>{
</span>  </span>// Config number, interface count, string index, total length, attribute, power in mA
</span>  </span>TUD_CONFIG_DESCRIPTOR</span>(</span>1</span>,</span> ITF_NUM_TOTAL</span>, </span>0</span>,</span> CONFIG_TOTAL_LEN</span>, </span>0x00</span>, </span>100</span>)</span>,
</span>
</span>  </span>// 1st CDC: Interface number, string index, EP notification address and size, EP data address (out, in) and size.
</span>  </span>TUD_CDC_DESCRIPTOR</span>(ITF_NUM_CDC_0</span>, </span>4</span>,</span> EPNUM_CDC_0_NOTIF</span>, </span>8</span>,</span> EPNUM_CDC_0_OUT</span>,</span> EPNUM_CDC_0_IN</span>, </span>64</span>)</span>,
</span>
</span>  </span>// 2nd CDC: Interface number, string index, EP notification address and size, EP data address (out, in) and size.
</span>  </span>TUD_CDC_DESCRIPTOR</span>(ITF_NUM_CDC_1</span>, </span>4</span>,</span> EPNUM_CDC_1_NOTIF</span>, </span>8</span>,</span> EPNUM_CDC_1_OUT</span>,</span> EPNUM_CDC_1_IN</span>, </span>64</span>)</span>,
</span>}</span>;
</span>
</span>// array of pointer to string descriptors
</span>char const</span>*</span> string_desc_arr [] </span>=
</span>{
</span>  (</span>const char</span>[]) { </span>0x09</span>, </span>0x04 </span>}</span>, </span>// 0: is supported language is English (0x0409)
</span>  </span>"TinyUSB"</span>,                     </span>// 1: Manufacturer
</span>  </span>"Private Inc"</span>,                 </span>// 2: Product
</span>  </span>"123456"</span>,                      </span>// 3: Serials, should use chip ID
</span>  </span>"TinyUSB CDC"</span>,                 </span>// 4: CDC Interface
</span>}</span>;
</span>
</span>// ...
</span></code></pre>
stm32fxxx_it.c</h2>
As mentioned in the beginning, the code inside the global interrupt handler needs to be modified.
In there tud_int_handler()</code> is called to hand the handling of the interrupt to TinyUSB. By returning early, the
"normal" interrupt handler code is prevented to be run, because it could interfere with TinyUSB.</p>
// stm32fxxx_it.c
</span>
</span>//...
</span>
</span>void </span>OTG_FS_IRQHandler</span>(</span>void</span>)
</span>{
</span>  </span>/* USER CODE BEGIN OTG_FS_IRQn 0 */
</span>  </span>return </span>tud_int_handler</span>(BOARD_DEVICE_RHPORT_NUM)</span>;
</span>
</span>  </span>/* USER CODE END OTG_FS_IRQn 0 */
</span>  </span>HAL_PCD_IRQHandler</span>(</span>&</span>hpcd_USB_OTG_FS)</span>;
</span>  </span>/* USER CODE BEGIN OTG_FS_IRQn 1 */
</span>
</span>  </span>/* USER CODE END OTG_FS_IRQn 1 */
</span>}
</span>
</span>// ...
</span></code></pre>
main.c</h2>
Then finally in main.c</code> the library is initialized with tusb_init()</code> after the clock and peripheral initialization
of the HAL. In the main loop tud_task()</code> is repeatedly called to handle all pending events in TinyUSB's internal event
queue.</p>
For the CDC example there is also some code to echo the received input from either CDC interface to both in either
lower- and uppercase.</p>
// main.c
</span>
</span>// ...
</span>#include </span>"ctype.h"
</span>#include </span>"tusb_config.h"
</span>#include </span>"tusb.h"
</span>// ...
</span>
</span>static void </span>echo_serial_port</span>(</span>uint8_t </span>itf</span>, </span>uint8_t </span>buf</span>[]</span>, </span>uint32_t </span>count</span>)</span>;
</span>static void </span>cdc_task</span>(</span>void</span>)</span>;
</span>
</span>int </span>main</span>(</span>void</span>) {
</span>  </span>// ...
</span>
</span>	</span>tusb_init</span>()</span>;
</span>
</span>	</span>while </span>(</span>1</span>) {
</span>		</span>tud_task</span>()</span>; </span>// TinyUSB device task
</span>		
</span>		</span>cdc_task</span>()</span>; </span>// CDC example
</span>		</span>// ...
</span>	}
</span>}
</span>
</span>// ***
</span>
</span>// echo to either Serial0 or Serial1.
</span>// with Serial0 as all lower case, Serial1 as all upper case.
</span>static void </span>echo_serial_port</span>(</span>uint8_t </span>itf</span>, </span>uint8_t </span>buf</span>[]</span>, </span>uint32_t </span>count</span>) {
</span>  </span>uint8_t </span>const</span> case_diff </span>= </span>'a' </span>- </span>'A'</span>;
</span>
</span>  </span>for </span>(</span>uint32_t</span> i </span>= </span>0</span>;</span> i </span><</span> count</span>;</span> i</span>++</span>) {
</span>    </span>if </span>(itf </span>== </span>0</span>) {
</span>      </span>// echo back 1st port as lower case
</span>      </span>if </span>(</span>isupper</span>(buf[i]))
</span>        buf[i] </span>+=</span> case_diff</span>;
</span>    } </span>else </span>{
</span>      </span>// echo back 2nd port as upper case
</span>      </span>if </span>(</span>islower</span>(buf[i]))
</span>        buf[i] </span>-=</span> case_diff</span>;
</span>    }
</span>
</span>    </span>tud_cdc_n_write_char</span>(itf</span>,</span> buf[i])</span>;
</span>  }
</span>  </span>tud_cdc_n_write_flush</span>(itf)</span>;
</span>}
</span>
</span>// USB CDC
</span>static void </span>cdc_task</span>(</span>void</span>) {
</span>  </span>uint8_t</span> itf</span>;
</span>
</span>  </span>for </span>(itf </span>= </span>0</span>;</span> itf </span><</span> CFG_TUD_CDC</span>;</span> itf</span>++</span>) {
</span>    </span>// connected() check for DTR bit
</span>    </span>// Most but not all terminal client set this when making connection
</span>    </span>// if ( tud_cdc_n_connected(itf) )
</span>    {
</span>      </span>if </span>(</span>tud_cdc_n_available</span>(itf)) {
</span>        </span>uint8_t</span> buf[</span>64</span>]</span>;
</span>        </span>uint32_t</span> count </span>= </span>tud_cdc_n_read</span>(itf</span>,</span> buf</span>, </span>sizeof</span>(buf))</span>;
</span>        </span>// echo back to both serial ports
</span>        </span>echo_serial_port</span>(</span>0</span>,</span> buf</span>,</span> count)</span>;
</span>        </span>echo_serial_port</span>(</span>1</span>,</span> buf</span>,</span> count)</span>;
</span>      }
</span>    }
</span>	}
</span>}
</span>
</span>// ...
</span></code></pre>
Testing</h1>
Before running the code, it is advisable to enable debugging and logging at first by setting CFG_TUSB_DEBUG</code> to a value
greater than zero in the configuration file. By default TinyUSB is logging with printf()</code>. To be able to inspect these
entries over e.g. UART, _write()</code> can be overwritten with something like:</p>
// main.c
</span>
</span>// ...
</span>
</span>int </span>_write</span>(</span>int </span>file</span>, </span>char </span>*</span>ptr</span>, </span>int </span>len</span>) {
</span>  </span>return </span>HAL_UART_Transmit</span>(</span>&</span>huart2</span>, </span>(</span>uint8_t</span>*</span>) ptr</span>,</span> len</span>,</span> HAL_MAX_DELAY)</span>;
</span>}
</span>
</span>// ...
</span></code></pre>

    
        </a>
    </div>
</aside>
This is it! The code should now compile and run on the MCU. Once the USB peripheral is connected to the host,
a USB device should appear with Vendor ID 0xCafe</code> and two CDC devices. They should appear as virtual-COM Ports in the
"Device Manager" on Windows or by inspecting the output of lsusb</code> on Linux.</p>
To connect to both CDC's a serial terminal tool can be used, for example tio</code>. On linux execute tio /dev/ttyACM<x></code>
for both devices.

Then, whenever something is typed into one of the terminals it should be echoed by both in lower- and uppercase.</p>


Hello from the future
2022-01-02T00:00:00+00:00
Well, this is actually written in the future, in November 2024.
Here used to be a rather uninspired first "Hello World" blog entry,
but I thought it would be nicer to properly welcome you to my blog.</p>
So, welcome!</p>
I am glad you have found my tiny corner of the internet interesting enough to click on this post and read through
this.
I used to think I needed to create a cooperate-friendly blog to put on my resume,
but I am realizing that nobody really cares about that anyways!
So am planning to make it more personal, to fill it more with my actual life and personal thoughts.</p>
I hope you enjoy.</p>


Rnote
2022-01-01T00:00:00+00:00



vecdisp
2020-10-01T00:00:00+00:00

blog.flxzt.net

pb-cheatsheet

Dynamic Cheatsheets on Pocketbook E-Reader

Host</h2>

CLI</h3> The following commands are implemented:</p>

Fetching Info</h3> Retrieving the focused window is implemented only for the Gnome desktop environment, because unfortunately there is no universal Wayland protocol yet that would enable a desktop environment independent implementation.</p>

Service</h3> The pb-cheatsheet-host report-focused-window</code> command continuously fetches info about the current focused window and reports it to the client over GRPC when it changes.</p> This command can be a service that is started by systemd. A suitable .service</code> file:</p>

Persistence</h3> The cheatsheets and the metadata containing the tags are saved as files whenever changes are made and when the app is closed. The populated save directory looks like this:</p>

ink-stroke-modeler-rs

Mercury

wave

Splot

Motion & Gesture Recognition for low-res TOF-Sensors

TinyUSB on STM32 MCU's with STM32CubeIDE

usb_descriptor.c</h2> Add usb_descriptors.c</code> in Core/Src/</code>. This file is for configuring the USB descriptors.</p>

Hello from the future

Rnote

vecdisp