SideShow

eInk display Badge based on the Pinorami InkyFrame.

How does it work?

SideShow uses the built-in SD Card reader combined with the PCF RTC to run as a super low power badge by displaying images on the eInk display.

States

Automatic

With the default configration, the device will "wake-up" every 15 minutes automatically and update the display. When not processing anything, the device will attempt to turn itself off to save power when using the JST battery connector on the InkyFrame board.

The display update process follows the following routes:

• Increase the "current display" count (held in PCF memory) by 1.
  • If the "current display" count is >= 127, reset it to 0.
• Open the /backgrounds directory (changable by configuration) on the SD Card.
  • Get the current file count in this directory
  • Choose a random image from this directory and write it's parsed contents to the eInk display buffer.
• Open the /badges directory (changable by configuration) on the SD Card,
  • Iterate through the files in the directory until one of the following conditions are met.
    • File count equals the "current display" count.
    • File is the last file in the directory.
  • If the file was the last entry, the "current display" count will be set to 127.
  • Write the selected image's parsed contents to the eInk display buffer.
• Update the eInk display.

The dual background and "badge" images work on the concept that TGA images allow for transparency, which is supported by our TGA parser. Transparent pixels will not be drawn and can allow for the previously drawn pixels to show through.

This selection process allows for randomized backgrounds for every "badge" displayed.

NOTE: SideShow will only read TGA-type image files. You can use imagmagick to convert them easily using convert src.jpg dst.tga

It's also recommended that the images are the size of the eInk display (640x400 for InkyFrame4, 600x448 for InkyFrame5) as SideShow will draw them at (0, 0) directly.

Buttons

The button configuration can be changed but supports the following button actions:

• Lock: Prevent the current "Badge" from being changed automatically. This will change the background but not the "Badge". When this action is used, the top LEDs (Action and Network) will display the new Lock state. It's a toggle button to switch the Lock state.
  • Action On, Network Off: Lock is Disabled.
  • Action Off, Network On: Lock is Enabled.
• Random: Select a random "Badge" and background and display it. This will override the Lock value and disable it. The "current display" count will be set to the current "Badge" position.
• Previous: Select the previous "Badge" and display it. The "current display" count will be set to the current "Badge" position (-1). This button does not override the Lock, if set. If the current "Badge" is the first entry (0), the "current display" value will be set to 127, which wraps around the selection.
• Next: Select the next "Badge" and display it. The "current display" count will be set to the current "Badge" position (+1). This button does not override the Lock, if set. If the current "Badge" is the last entry, the "current display" value will be set to 0, which wraps around the selection.
• Custom: TODO.

The default button configuration is:

• A: Nothing
• B: Lock
• C: Random
• D: Previous
• E: Next

When a button is pressed, it's LED will light up indicating the pressed selection.

Errors

If SideShow encounters an error, it will switch to an error state and will require it to be power-cycled to clear it.

Error states are indicated by the Activity and Network LEDs flashing back-and-forth every second. Which button LEDs are lit up indicate the type of error that occurred.

The work by @ticky has allowed for expansion of the error types for better debugging. The resulting error code will be in 5-bit binary. The table mapping of the LEDs to the errors is listed below.

Error Descriptions

• Byte: Operations on the PCF stored byte failed.
• Wake: Operations on the PCF wake alarm and interrupts failed.
• InvalidPins: Setup for the eInk display was not correct. Usually this error is due to a configuration/code error.
• InvalidRoot: Operations on the SD Card (non-image related) failed. This is usually due to an error with the SD Card or it's formatting. Sometimes it will be a fluke issue, but may require re-formatting the SD Card if the error occurs multiple times in a row.
• Badge/DirOpen: Generic error occurred when trying to open the Badge directory.
• Badge/DirNotFound: The Badge directory could not be found.
• Badge/DirNotADir: The Badge directory was found, but it's type was not a directory.
• Badge/DirList: Reading the Badge directory listing failed.
• Badge/DirListReset: Resetting and re-reading the Badge directory listing failed.
• Badge/DirIter: Walking through the Badge directory listing failed.
• Badge/ImageIo: Reading the selected Badge file failed. (During Parsing, but not format related).
• Badge/ImageType: The selected Badge image type was not a valid TGA file.
• Badge/ImageRead: Generic parsing/reading error occurred when reading the selected Badge file.
• Badge/ImageParse: The selected Badge image could not be parsed due to improperly returned TGA data. (Corrupted or badly formatted file?).
• Background/DirOpen: Generic error occurred when trying to open the Background directory.
• Background/DirNotFound: The Background directory could not be found.
• Background/DirNotADir: The Background directory was found, but it's type was not a directory.
• Background/DirList: Reading the Background directory listing failed.
• Background/DirListReset: Resetting and re-reading the Background directory listing failed.
• Background/DirIter: Walking through the Background directory listing failed.
• Background/ImageIo: Reading the selected Background file failed. (During Parsing, but not format related).
• Background/ImageType: The selected Background image type was not a valid TGA file.
• Background/ImageRead: Generic parsing/reading error occurred when reading the selected Background file.
• Background/ImageParse: The selected Background image could not be parsed due to improperly returned TGA data. (Corrupted or badly formatted file?).
• Panic: Generic Rust panic occured. Run with the "debug" feature to determine the source.

Error Mapping Table

To display the error codes, the button LEDs will light up to display a 5-bit binary number. (A = 16, B = 8, C = 4, D = 2, E = 1).

Due to numbering, most Background related errors will have the "A" LED enabled.

Critical Errors

There are two odd "critical" type errors that will only happen during initialization. The code for them is located here. This error type does not use the Activity or Network LEDs.

The two conditions are:

• A | B: Stack overflow in critical section. This error is super rare. If you receive this error, attempt to run Sideshow with the static or static_large feature flags. If that still fails, please leave an Issue.
• D | E: SDCard initilization error. This error occurs when the SDCard does not respond properly to the INIT (CMD0) command and may indicate a bad SDCard or one that does not support SPI. If you receive this error, try another SDCard if avaliable. If you can't or the other one fails with the same error, please leave an Issue with information on the SDCard and it's manufactor, size and class markings (eg: C with the number, U with the number, etc.). This should be fixed now, see the Bugs section below!

Configuration

The configuration is fairly simple. Any changes made are in sideshow.rs in the following code block:

// =================== [   Configuration   ] ===================
/// Time in milliseconds) to wait for a button check. Only
/// takes affect when NOT on battery power.
const SLEEP_STEP: u32 = 50u32;
/// Time (in seconds) to wake up and change the current
/// badge and/or background.
const SLEEP_TIME: u32 = 15u32 * 60u32;

/// Directory name in the SD Card root to get the badge
/// images from.
const DIR_BADGES: &str = "/badges";
/// Directory name in the SD Card root to get the background
/// images from.
const DIR_BACKGROUNDS: &str = "/backgrounds";

/// Action to return when the 'A' button is pressed.
const BUTTON_A: Action = Action::None;
/// Action to return when the 'B' button is pressed.
const BUTTON_B: Action = Action::Lock;
/// Action to return when the 'C' button is pressed.
const BUTTON_C: Action = Action::Rand;
/// Action to return when the 'D' button is pressed.
const BUTTON_D: Action = Action::Prev;
/// Action to return when the 'E' button is pressed.
const BUTTON_E: Action = Action::Next;
// =================== [ Configuration End ] ===================

Each name is self-explanatory and any changes require a re-compilation and upload to the device to take affect.

Setup

To start using SideShow, you'll need to compile this repository first.

The cargo configuration should contain all the values needed to compile in the thumbv6m-none-eabi target format (for the RP2040 processor). You'll need to make sure you have the flip-link linker installed before compiling. To do this, use the command cargo install flip-link to install it.

If a Pico debug probe is avaliable (or you can setup one, see here), installing probe-rs using cargo install probe-rs-tools will allow for direct flashing of the firmware when the probe is connected to the SideShow device when cargo run is called.

If you don't have a debug probe avaliable, you can convert the compiled ELF into a U2F file using elf2uf2-rs (cargo install elf2uf2-rs) and can be loaded using the Bootloader mode of the Pico (hold down the "Boot" button when plugging the device in to expose the flash storage) by copying the generated file over to flash. Make sure to comment out the first two lines of .cargo/config.toml to avoid any compilation errors.

Case

Included in the case directory are STL files that can be used to 3d-print a nice case to contain the device with:

• USB-C connector port
• Simple switch (for on/off)
• LiPo Battery Pack
• AdaFruit PowerBoost 1000

InkyFrame Devices

The current code configuration is support for the InkyFrame 4. With a couple of code and configuration changes, it can work on different devices or larger screen sizes.

If using an InkyFrame5, build with the "inky5" feature. This will also use the "static_large" feature for the larger screen.

See the InkyFrame repository for compatibility.

Stupid Notes

If you have the device on battery (via JST) and it wakes up way too early or instantly. Unplug it from the battery and let it sit for a minute, sometimes the PCF gets wonky and needs a lil reset.

Bugs

• Files named from MacOS are not correctly found by their name, even when correct. Thanks to @ticky for the finding

SDCard Bugs

This should be fixed with the inky-frame v0.3.0 update! Turns out some cheap vendors don't follow standard protocols, weeeeee!

Copied from the inky-frame README.

Some SDCards don't support SPI mode or don't initialize properly. I'm not 100% sure if it's a protocol issue or something else. These cards return READY (0) when asked to go into IDLE (1) mode. They'll work fine on PCs.

These SDCards work fine on some of my Ender 3 3D Printers, which use Arduino's SDCard library and have the same initializing sequence. But other devices, like the Flipper Zero, don't work with them either.

You'll know if it fails as it won't get past the initialization phase and basically "freezes" and does not respond with the "D" and "E" LEDs on. This error type does not use the Activity or Network LEDs.

If you have a SDCard that has issues also, please leave me an Issue with information on the SDCard and it's manufactor, size and class markings (eg: C with the number, U with the number, etc.) so I can test further.

SDCards verified to not work:

• These SDHC Class 10/U1 Cards