🔍
v1.3.8

Hardware Overview

TSharkRex recipes run on a family of XBB hardware devices. While you write the same language regardless of device, each product has different capabilities, form factors, and intended use cases. Understanding these differences helps you write recipes that work correctly on your target hardware.

Product Comparison

The table below summarizes the three main XBB product lines:

Product Form Factor CAN Mode Wake-up Use Case
XBB Dongle (v1) OBD connector NORMAL Gyro Removable, UDS requests
XBB Dongle-2 OBD connector NORMAL Gyro + Analog Removable, UDS + CAN-FD
PP-CAN-FD Permanent mount NORMAL / SILENT Voltage Permanent install, CAN + CAN-FD

Hardware Type Identifiers

Each hardware product has a numeric type identifier used internally by the compiler and runtime. You may encounter these values in recipes, firmware metadata, or diagnostic logs:

Constant Value Product
XBB_DONGLE 0 XBB Dongle (v1)
XBB_DONGLE_2 1 XBB Dongle-2
XBB_PPCAN 2 PP-CAN-FD (original)
XBB_PPCAN_2 3 PP-CAN-FD (revision 2)
XBB_DONGLE_2 and XBB_PPCAN / XBB_PPCAN_2 share the same underlying hardware (ARM Cortex-M4 with CAN-FD transceiver). The differences lie in form factor, default CAN mode, and wake-up mechanism.

XBB Dongle (v1)

The original XBB Dongle is a compact device that plugs directly into the vehicle’s OBD-II diagnostic port. It is designed for removable installation - you can plug it in and unplug it without any wiring modifications.

Key Features

Typical Use Cases

XBB Dongle-2

The second-generation dongle keeps the same plug-and-play OBD-II form factor but adds significant hardware improvements.

Key Features

Typical Use Cases

PP-CAN-FD

The PP-CAN-FD is designed for permanent installation inside the vehicle, typically spliced directly onto an internal CAN bus (e.g., chassis CAN, body CAN, or a specific gateway bus).

Key Features

Note

PP-CAN-FD recipes commonly use SILENT mode for passive CAN reading, but the hardware is fully capable of transmitting CAN frames. You can use NORMAL mode and send UDS requests if needed. The choice of SILENT vs NORMAL is a recipe design decision, not a hardware limitation.

Typical Use Cases

Dongle-2 vs. PP-CAN-FD

It is important to understand that the Dongle-2 and PP-CAN-FD share the same hardware platform. The silicon, processor, memory, and CAN-FD transceiver are identical. The differences are:

Aspect Dongle-2 PP-CAN-FD
Form factor OBD-II plug Bare wires, permanent mount
Default CAN mode NORMAL (send + receive) SILENT (receive only)
Wake-up Gyro + Analog Voltage
Standard libraries UDS wake-up library PP-CAN wake-up library
Installation Removable, user-installable Permanent, professional install

When you create a recipe on the TSharkRex Platform, you select the target hardware type. The platform then includes the correct standard libraries (UDS-based or PP-CAN-based) and configures the appropriate CAN mode and wake-up behavior.

PowerUnit

The PowerUnit is an external output module that connects to the XBB dongle via the mobile app. It provides additional high-power output channels for driving relays, LEDs, and other accessories that require more current than the dongle’s built-in outputs can supply.

In your TSharkRex code, PowerUnit outputs are declared and controlled exactly like dongle outputs - the routing to the physical PowerUnit hardware is handled by the runtime and the app.

VAR_SIGNAL
    SIGNAL_HELLJUS : BOOL;   // High-beam signal
END_VAR;

VAR_OUTPUT
    PU_KANAL_1 : OUTPUT;   // PowerUnit channel 1
    PU_KANAL_2 : OUTPUT;   // PowerUnit channel 2
END_VAR;

// Outputs always called every cycle
PU_KANAL_1(VALUE := SIGNAL_HELLJUS * 1000, PERIOD := 1000);            // Full brightness
PU_KANAL_2(VALUE := SIGNAL_HELLJUS * 500, PERIOD := 1000);  // 50% PWM

Smart Button

The Smart Button is an optional Bluetooth-connected button that can trigger actions in your recipe. It supports three press patterns:

Each press pattern can be mapped to different behavior in your recipe. This gives end users a physical control interface without needing to open the mobile app. Common use cases include toggling lighting modes, cycling through output patterns, or activating/deactivating recipe features.

VAR_SIGNAL
    HW : HARDWARE;         // Must be declared to access button
END_VAR;

VAR_OUTPUT
    LJUS : OUTPUT;
END_VAR;

VAR
    ljus_lage : INT := 0;  // 0=off, 1=on, 2=flash
    ljus_varde : INT;
    TMR_BLINK : TON;
    blink_state : BOOL;
END_VAR;

HW();  // Update hardware readings each cycle

// HW.BUTTON is edge-triggered: value is only present for ONE cycle
// No R_TRIG needed - just check the value directly
IF HW.BUTTON = 1 THEN             // BUTTON_CLICK (single press)
    ljus_lage := ljus_lage + 1;
    IF ljus_lage > 2 THEN
        ljus_lage := 0;
    END_IF;
END_IF;

IF HW.BUTTON = 3 THEN             // BUTTON_LONGCLICK (long press)
    ljus_lage := 0;                // Force off
END_IF;

// Blink timer for flash mode (self-resetting, toggles every 200ms)
TMR_BLINK(IN := NOT TMR_BLINK.Q, PT := T#200ms);
IF TMR_BLINK.Q THEN
    blink_state := NOT blink_state;
    TMR_BLINK(IN := FALSE);
END_IF;

// Calculate output value based on mode
CASE ljus_lage OF
    0: ljus_varde := 0;                    // Off
    1: ljus_varde := 1000;                 // Steady on
    2: ljus_varde := blink_state * 1000;   // Flashing on/off
END_CASE;

// Output always called every cycle
LJUS(VALUE := ljus_varde, PERIOD := 1000);

CAN Bus Modes Explained

The CAN mode determines how the device interacts with the vehicle’s CAN bus. TSharkRex defines several CAN modes that you will encounter in recipes and standard libraries:

Mode Description Can Send? Can Receive?
CAN_MODE_NORMAL Full bus participation Yes Yes
CAN_MODE_SILENT Listen-only, no transmit No Yes
CAN_MODE_SLEEP Low-power sleep No No
CAN_MODE_DEEP_SLEEP Lowest power consumption No No
CAN_MODE_CONFIG Configuration / initialization No No
In most recipes, you do not set the CAN mode directly. The standard wake-up libraries handle mode transitions automatically. You only need to understand CAN modes if you are writing custom wake-up logic or troubleshooting bus communication issues.

Choosing the Right Hardware

Use this decision guide to pick the right XBB product for your project: