Skip to content

Events display

Tomasz Klim edited this page Jan 10, 2022 · 28 revisions

Mobile Badger is designed to run in full headless mode (without monitor, and without auto-logging on local console).

However, there is a way to control its activities - it supports various LED/LCD displays:

Device model(s) Installing Notes
Adafruit PiTFT 2.2/2.8 inch LCD manual framebuffer-based
BakeBit NanoHat OLED manual for NanoPi NEO/NEO2, not Raspberry Pi
BlinkStick Strip manual USB instead of GPIO; our recommended device
Pimoroni Blinkt! manual our recommended device
Pimoroni Scroll HAT Mini manual
Uctronics 3.5 inch Touchscreen manual framebuffer-based; avoid it
Waveshare 1.44inch LCD display HAT manual
Waveshare True color RGB LED HAT manual

Here you will find a repository containing the current list of drivers, along with their documentation.

The idea

Data exfiltration takes time, especially when run on relatively slow device, instead on a normal computer. Therefore it is crucial to know, what is actually happening with this device:

  • was the attached target drive properly recognized?
  • was the user drive properly recognized and decrypted?
  • is the exfiltration still running, or already finished?
  • any other important events?

The easiest way to handle this, especially in the field use, is to use simple LED interface, that will show such event using multiple LED colors, eg.:

Slots

While there multiple different display devices supported, where each of them has completely different capatilibies, there is a common idea of slots. Each device needs to display from 8 to 10 slots, counted from 0 to 7/8/9, where each slot is represented as:

  • multi-color LED pixel
  • LED column in a matrix LED display
  • text row on LCD display
  • any other method, that can show at least 6 states (including off)

For all currently supported devices, slot 0 means the first LED pixel or first text row.

Each driver has its own module that translates events generated by Mobile Badger to physical capabilities of the device. For example, for Waveshare True color RGB LED HAT it looks:

$events = array (
    "shutdown"                => array(-1, "off"),
    "ready"                   => array(0, "yellow"),
    "target_ready"            => array(0, "green"),
    "target_disconnected"     => array(0, "yellow"),
    "media_device_detected"   => array(7, "green"),
    "media_device_processed"  => array(7, "off"),
    "operation_started"       => array(-2, "green"),
    "operation_finished"      => array(-2, "off"),
);

Where the color names of particular LED pixels are also translated to color codes:

$colors = array (
    "off"    => array(  0,   0,   0),
    "red"    => array(255,   0,   0),
    "green"  => array(  0, 255,   0),
    "blue"   => array(  0,   0, 255),
    "orange" => array(255,  30,   0),
    "yellow" => array(255,  70,   0),
    "purple" => array(255,   0, 255),
    "white"  => array(255, 255, 255),
);

Global, per-device and per-partition events

There are exactly 8 types of events, from which half of them are global (mapped to slot 0), while the other half are related to exfiltrated devices - where slot number is mapped to device and partition number. Thanks to it, a simple 8 LED display can simultaneously show stages of up to 7 parallel operations.

Global events (slot 0):

  • shutdown - turn of all display, disable all LED pixels etc., depending on device type
  • ready - Mobile Badger device is ready to work after boot
  • target_ready - target drive was connected, recognized and mounted
  • target_disconnected - target drive was disconnected, fallback drive will be used

Per-device events (always last slot):

  • media_device_detected - MTP/PTP device was detected, and its exfiltration is about to start
  • media_device_processed - MTP/PTP exfiltration is done

Per-partition events (slots 1 to 7..9):

  • operation_started - hard drive was detected, and its exfiltration is about to start; each partition gets its own event, eg. /dev/sdb1 is mapped to slot 1, /dev/sdb2 mapped to slot 2 and so on
  • operation_finished - partition exfiltration is done

This way, if you connect a modern Windows drive with many hidden/recovery/reserved partitions, you will always properly see, which operations are done, and which are still in progress.

Technical aspects

Connectors and compatibility

Mobile Badger supports 3 types of connectors:

  • 40-pin connector, placed along the top edge of the board
  • includes 3 different interfaces: I2C, SPI and UART
  • compatible with all Raspberry Pi models since B+, and with various clones (unfortunately except NanoPi)
  • most supported display devices use this connector
  • Raspberry Pi boards are sold in 2 version: with or without soldered GPIO connector (pay attention, which version you're buying)
  • 24-pin connector
  • similar idea to GPIO connector for Raspberry Pi, but not compatible
  • compatible only at Python level, using RPi.GPIO library (NanoPi has a dedicated version)
  • currently used only by BakeBit NanoHat OLED device, integrated with recommended NanoPi-NEO2 board
USB:
  • currently supports only BlinkStick Strip devices, but driver can be easily adapted to other BlinkStick models
  • main advantage of USB displays is the possibility of (dis)connecting them during work - so the operator can change display device during exfiltration in progress (eg. from mobile display, to bigger display integrated in car dashboard)

Native and framebuffer-based drivers

Most display devices has native drivers, which means, that the program "tells" the device eg. to light a specific LED pixel to specific color, or draw a geometric figure (or character) on LCD display.

Some devices however have only framebuffer-based drivers - they act like monitors showing the image from the HDMI output. Such devices - especially models supporting touch functionality, or at least having some physical buttons - can be a great solution for interactive kiosks (ticket machines, McDonald's ordering machines etc.). But all of them have one major disadvantage: the whole system has to work in graphical mode, with automatic login ad start of the kiosk application.

Mobile Badger works in a different way: fully headless, without any user interface. It detects connected devices using udevd and handles them as systemd ephemeral services, completely in background. Nothing is displayed on physical console, except for standard Linux logging prompt, so framebuffer-based devices can't work.

That's why Mobile Badger handles framebuffer-based devices in a completely different way:

  • on each change, buffer file with previous content is loaded
  • change is applied to that buffer file and saved again
  • new image is generated and saved to a file
  • new image file is copied to /dev/fb1 device

This approach works, but is obviously inefficient and slows down the whole Mobile Badger device. Therefore, we generally advise against buying display devices having only framebuffer-based drivers (if you have a native model to choose from).

What if a drive has more than 7..9 partitions?

Mobile Badger supports display devices having from 8 to 10 slots, from which slot 0 is reserved for global events - so just 7 to 9 are available for per-partition events (and last slot is shared with events from MTP/PTP devices: phones, tablets, photo cameras etc.).

If you connected a hard drive (or even pen drive) that has more than 7..9 partitions:

  • all partitions will be exfiltrated
  • partitions 8..10 and upper just won't be handled in any way on display (and thus will be exfiltrated silently)

What if you connect many drives simultaneously?

Mobile Badger can exfiltrate many drives simultaneously - the only limitation is physical performance (CPU speed, enough RAM) of your chosen hardware platform.

However, event display interface supports only partition numbers, without drive identifiers - so if you connect many drives simultaneously, then events from different drives will mix up on the display device, which probably will be confusing, since you won't be sure, which operations really finished, and which are still in progress.

What if you connect many MTP/PTP devices simultaneously?

Mobile Badger can exfiltrate many MTP and PTP devices simultaneously - at least theoretically, since some devices implement MTP/PTP protocols in non-standard way, which can sometimes result in blocking the whole interface. Nevertheless, it is always possible at least to connect 1 MTP and 1 PTP device at the same time.

However, event display interface supports all MTP/PTP exfiltration operation on last slot only - so if you connect more than 1 such device, then events from different devices will mix up, which probably will be confusing, since you won't be sure, which operation(s) really finished, and which are still in progress.

Similarly, in case of simultaneous exfiltration of MTP/PTP devices and a drive with more than 7..9 partitions - events will mix up on the display (while exfiltration processes will be carried out without any complications).