OBD Widgets - Android Widgets for OBD2 Data

An Android app for displaying OBD2 data as interactive widgets on the home screen. Specifically optimized for integration into Car Launcher Pro or as a standalone dashboard extension, without the need for a heavy main app running in the foreground.

Screenshot

Core Features

Peak Hold Functionality:

- Track maximum values for parameters like RPM, Speed, and Boost. - Visual indicators (yellow bars) on Analog and Circular widgets mark the peak value. - Manual reset via a dedicated "Peak Reset Button" widget. - Automatic reset on app/service start. - Toggleable per widget in the configuration dialog.

Vehicle Profiles & Editor: Create and edit profiles to store gear ratios, final drive ratios, and tire circumference.
Intelligent Gear Display: Real-time calculation of the current gear based on RPM and speed using profile data.
Shift Indicator:

- Modes: FLASH (blinking) or COLOR (color change of the value/bar). - Gear-dependent shift points based on the current driving mode. - Automation: Sends broadcasts for external tools (e.g., MacroDroid) when shift points are reached.

Autoplay Music: Automatically starts music if no audio is detected after the drive starts. Supports direct control of YouTube Music, Spotify, or generic system play commands.
Custom PID Editor: Create and configure vehicle-specific OBD parameters.

- Supports custom formulas for data processing (e.g., (A*256+B)/4). - Variables A, B, C, D map to the bytes of the OBD response. - Configurable units, ranges (min/max), and display names.

Color Profile Editor: Create and manage custom color schemes for all widget types.
Advanced Driving Mode Detection: A scoring system automatically detects the driving style (Economy, Normal, Sport) by analyzing load (throttle), RPM, and speed.
Test Mode: Simulation of the entire data pipeline for UI testing without a Bluetooth connection. Includes dynamic state cycling (0-4) and gear simulation.
Tasker/MacroDroid Integration: Extensive broadcasts for automation on status changes or threshold events.
MQTT Integration: Sends MQTT Data to broker and can receive data to show on a secondary device. Optimized for real-time fluid updates of RPM and Speed.

Technical Highlights (Stability & Watchdog)

To ensure reliable operation in permanent automotive use, the app implements the following systems:

Heartbeat System: An AlarmManager-based periodic check ensures that the service remains active even under aggressive Android power management (Doze Mode).
Watchdog Monitor:

- Detects "stale" states (data stream interruption). - Monitors connection status and automatically triggers a reconnect ("kick") if the connection hangs.

Foreground Service: Implemented as a connectedDevice service to maintain maximum priority and continuous access to the Bluetooth stack.
WakeLock Management: Active management of partial WakeLocks to prevent deep sleep during driving.
Optimized Rendering: Widgets are rendered directly onto bitmaps to minimize CPU load for RemoteViews updates.

Requirements & Permissions

Minimum Requirements

Android 5.0+ (API Level 21+)
Bluetooth OBD2 Adapter: ELM327 / STN11xx compatible (Vlink, OBDLink, etc.)

Required Permissions

BLUETOOTH_CONNECT & BLUETOOTH_SCAN: Necessary for discovery and communication with the OBD adapter (Android 12+).
ACCESS_FINE_LOCATION: Required for Bluetooth scanning on many Android versions.
FOREGROUND_SERVICE & FOREGROUND_SERVICE_CONNECTED_DEVICE: Allows the app to maintain the OBD connection while in the background.
POST_NOTIFICATIONS: To display the mandatory service notification and status.
RECEIVE_BOOT_COMPLETED: Enables the app to start automatically when the device boots (ideal for head units).
WAKE_LOCK: Prevents the CPU from entering deep sleep during an active driving session.
SCHEDULE_EXACT_ALARM: Used for the high-precision watchdog/heartbeat system.

Widget Types

Analog: Classic speedometer with needle and configurable scale steps. Supports Peak Hold.
Circular: Modern ring progress bar with a digital center. Supports Peak Hold.
Peak Reset Button: A compact 1x1 circular 3D button to globally reset all peak hold values.
Graph Bar: Curve progression of recent values with Bezier-smoothed animation.
Digital: High-contrast text display for quick readability.
Gear: Special visualization of the H-shifter with highlighting of the active gear.

OBD Parameters

The app reads PIDs in a configurable interval (default 50ms-100ms):

Core: Speed (km/h), RPM, Engine Load, Throttle Position.
Temperatures: Coolant Temp, Oil Temp.
Custom: User-defined PIDs via the integrated PID Editor.
Calculated: Virtually calculated Gear, Boost Pressure (bar/kPa).
Diagnostics: Battery Voltage (V), Fuel Level (%), Manifold Pressure (MAP).
System: Vehicle State (0-4).

Broadcast Interfaces (Intents)

Outgoing (for Automation/Tasker/MacroDroid)

com.obdwidgets.CONNECTED: Service is active and Bluetooth connection to the adapter is established.
com.obdwidgets.READY: OBD protocol is initialized and the app is actively polling vehicle data.
com.obdwidgets.VEHICLE_STATE_CHANGED: Triggered on every state transition. Extras: state (int), old_state (int).
com.obdwidgets.STATUS_CHANGE: Status change. Extra: status (DISCONNECTED, CONNECTING, ADAPTER_READY, WAITING_FOR_IGNITION, RUNNING, ERROR).
com.obdwidgets.DATA_UPDATE: Live data broadcast. Extras contain the values (keyed by PID or Name).
com.obdwidgets.SHIFT_INDICATOR: Triggered when the shift point is reached. Extra: is_shift (boolean).
com.obdwidgets.MQTT_STATUS_CHANGED: MQTT connection state. Extra: status.
com.obdwidgets.AUTOPLAY: Sent periodically if no music is detected after start (if mode is set to Broadcast).

#### Vehicle State Definitions (0-4)

0: DISCONNECTED: No active service or persistent connection error.
1: PRE_DRIVE: App/Service is active, adapter connected, but OBD pipeline not yet established.
2: DRIVE_READY: Ignition ON, OBD data flowing, but engine is OFF (RPM = 0).
3: ENGINE_RUNNING: Engine is ON (RPM > 0), but vehicle is stationary.
4: DRIVING: Vehicle is in motion (Speed > 0). Includes a 60s hysteresis when stopping to prevent state flickering in stop-and-go traffic.

Note: For reliable operation with MacroDroid, ensure you have enabled the desired intents in the app's Automation / Intents settings and used the "Test" button to verify reception.

Incoming (Control Actions)

com.obdwidgets.action.STOP_AND_RESET: Forces a full service reset and reconnection.
com.obdwidgets.action.PERIODIC_CHECK: Internal trigger for the stability watchdog.
com.obdwidgets.action.RESET_PEAKS: Resets all currently held peak values.

Architecture

app/
├── model/              # Data models (OBDParameter, CustomPID, VehicleProfile, OBDData, VehicleState)
├── obd/                # Protocol stack (ELM327 implementation, protocol handshake)
├── service/            # OBDService (Central Foreground Service &amp; Watchdog)
├── widget/             # WidgetProvider &amp; Canvas-based Bitmap rendering
├── ui/                 # Activities (Settings, ProfileEditor, ColorProfile, PIDEditor)
├── util/               # Helpers (LogManager, ModeDetector, ShiftIndicator)
└── receiver/           # BroadcastReceivers (Boot, Alarm, Resume, WakeDebug)

Comparison with Torque Pro

Feature	OBD Widgets	Torque Pro
UI Integration	Native Android Widgets	Own overlay layer / Widgets
Background Operation	Permanent Service	Often requires app in foreground
Gear Display	Calculated via profile	Via plugin / formula
Shift Indicator	Native widget animation	External plugin required
Peak Hold	Dedicated markers & Reset Button	Limited/requires manual setup
Startup Behavior	Fully automatic at boot	Partly delayed
Custom PIDs	Formula Editor (A,B,C,D)	Formula Editor

Manual & Feature Guide

1. MQTT Telemetry (Remote Dashboard)

This feature allows you to mirror your car's live data onto a secondary device (e.g., your smartphone) over the internet.

#### Setup: The Sender (Car/Head Unit)
1. Go to MQTT Settings.
2. Enter your MQTT Host (e.g., mqtt.netquick.ch).
3. Set a Vehicle ID (e.g., zafira). This is the "channel name" your car will send to.
4. Enable "MQTT Enabled" and "Send OBD Data".
5. The car will now publish data to car/zafira/obd/live.

#### Setup: The Receiver (Smartphone/Tablet)
1. Go to MQTT Settings.
2. Use the same MQTT Host.
3. (Optional) Set a different Vehicle ID for the phone (e.g., myphone) or leave it empty. *Do not use the car's ID here to avoid connection conflicts!*
4. Set the Remote ID to your car's ID (e.g., zafira).
5. Enable "MQTT Enabled" and "Receive MQTT Data".
6. Set Telemetry Source (under Data Source settings) to MQTT.
7. Your widgets will now show the car's data in real-time.

Note: Essential real-time parameters like RPM and Speed are updated with higher priority (at least every 500ms) to ensure a fluid remote display.

2. Watchdog & Stability System

The app is designed for permanent installation in car head units. To ensure it never hangs:

Heartbeat: Every 60 seconds, an alarm wakes the service to check if the connection is still alive.
Smart Ping: If the data stream from the Bluetooth adapter stops for more than 15 seconds, the watchdog sends an AT command. If the adapter doesn't respond, a Hard Reset is triggered to reconnect.
MQTT Watchdog: If MQTT is the data source, the app monitors the TCP connection to the broker and reconnects automatically if the network drops.

3. Peak Hold (Max Values)

Widgets can remember the maximum value reached during a session (e.g., max RPM or max Boost).

Visualization: A yellow bar/marker on the scale indicates the peak.
Configuration: Enable "Peak Hold" in the specific widget's settings.
Reset:

- Use the Peak Reset Button widget for a one-tap global reset. - Peaks are automatically reset when the service starts. - Send the broadcast com.obdwidgets.action.RESET_PEAKS via MacroDroid.

4. Vehicle Profiles

To calculate the Gear and Shift Points, the app needs your vehicle's specs:

Tire Circumference: In mm (e.g., 1985 for 225/40R18).
Final Drive: The differential ratio.
Gear Ratios: Individual ratios for gears 1-6.
Shift Points: Configurable RPM limits per gear for different driving modes (Economy, Normal, Sport).

5. Custom PID Editor

Create vehicle-specific parameters that are not part of the standard OBD2 set (e.g., Oil Temperature on some models).

PID: The hex code (e.g., 221105).
Formula: Use variables A, B, C, D representing the response bytes.

- Example: (A*256+B)/10

Configuration: Define unit (°C, bar), display name, and the min/max range for gauge scaling.

6. Color Profile Editor

Global styling for all widgets. You can create multiple profiles (e.g., "Night", "Sport-Red", "Eco-Green").

Customizable Colors: Needle/Bar color, Scale/Ticks, Value text, and Label.
Assignment: Each widget instance on the home screen can be assigned a different color profile in its configuration dialog.

7. Advanced Driving Mode Detection

The app features an intelligent scoring system that automatically switches between Economy, Normal, and Sport.

Logic: It analyzes the relationship between Throttle Position, RPM, and Acceleration.
Impact: Changing the mode updates the Intelligent Gear Display and adjusts the Shift Indicator thresholds in real-time.
Manual Override: Use the Driving Mode Button widget to manually lock a specific mode.

8. Test Mode (Simulation)

Perfect for desk-setup or testing widget layouts without being in the car.

Activation: Set Telemetry Source to Test Mode.
Behavior: The app generates realistic simulated data curves for all major parameters (RPM, Speed, Boost, etc.). It automatically cycles through vehicle states (0-4) and simulates gear changes based on speed.

9. Automation (MacroDroid / Tasker)

The app exposes several interfaces for external automation:

Trigger on State Change: Monitor the intent com.obdwidgets.VEHICLE_STATE_CHANGED to react to specific vehicle states (e.g., open a gate when state=4 or start music when state=3).
Trigger on Connection: Use the Intent com.obdwidgets.CONNECTED (Service/BT active) or com.obdwidgets.READY (OBD data flowing).
Trigger on Shift: The intent com.obdwidgets.SHIFT_INDICATOR (extra is_shift: true) can be used to trigger an external LED strip or sound via MacroDroid.
Configuration: Visit Settings > Automation / Intents to enable/disable and test specific intents.

10. Autoplay Music

Ensures music starts automatically when you begin your drive.

Function: Periodically checks for active audio output. If silent, it triggers the configured action.
Modes:

- YouTube Music / Spotify: Directly sends a "Play" command to the specific app. - System Standard: Sends a global media play command to the last active app. - Broadcast: Sends com.obdwidgets.AUTOPLAY for MacroDroid integration.

Smart Loop: Automatically stops after music is detected for 2 consecutive checks (10s) to allow manual control afterwards.

Screenshot

Screenshot

Services

Service A

Service B

Service C

Apps

DriveHub

OBDWidgets