Beaglebone Black OBD2: A Comprehensive Guide to Car Telematics and Data Exfiltration

Unlock the hidden data within your vehicle using the Beaglebone Black and OBD2 connectivity. This guide delves into building a sophisticated yet accessible car telematics system, “ChupaCarBrah,” that not only reads real-time vehicle diagnostics via the OBDII port but also integrates GPS tracking and cellular communication for remote data access. Whether you’re an automotive enthusiast, a budding car hacker, or a developer interested in vehicle data, this project provides a robust foundation for exploring the world of in-car networks and data analysis.

Building ChupaCarBrah: Your OBD2 Car Data Spy

“ChupaCarBrah” is designed as a discreet and powerful tool for extracting valuable data from your car’s CAN bus. By leveraging the Beaglebone Black (or Beaglebone Blue, as used in the original project) and a simple OBDII connection, you can tap into a wealth of information, from engine performance metrics to GPS location. This project outlines the necessary hardware, assembly steps, and software setup to get you started.

Parts List for Your Beaglebone Black OBD2 Project

To construct ChupaCarBrah, you’ll need the following components. This list ensures you have everything required to replicate the project and start exploring your car’s data.

Essential components for building the ChupaCarBrah car telematics device.

Beaglebone Black or Beaglebone Blue: The brains of the operation, providing the processing power and connectivity for OBD2 interaction, GPS, and cellular communication. Beaglebone Blue, specifically, is beneficial due to its integrated CAN bus and power management features.
OBDII Connector (Female): This connector plugs directly into your car’s OBDII port, providing the physical interface to the CAN bus and vehicle power.
JST/SH Connector: Used to connect hook-up wires to the Beaglebone’s CAN slot. This ensures a secure and reliable connection for CAN communication.
Hook-up Wires (Colored): Essential for connecting the Beaglebone to the OBDII connector and other components. Using colored wires (Black, Red, Yellow, Green) helps maintain consistent wiring and reduces errors during assembly.
DC Barrel Jack Adapter: Allows you to power the Beaglebone directly from the OBDII port’s 12V supply, simplifying the power setup.
GPS Module: Adds location tracking capability to your device, enabling geolocational data to be logged and transmitted alongside vehicle diagnostics.
Cellular Modem (USB): Provides internet connectivity via a cellular network, allowing for remote data transmission to a server for real-time monitoring and data logging. A Hologram.io modem is used in this example, but other USB cellular modems are compatible.
SIM Card (for Cellular Modem): A data-enabled SIM card is required for cellular communication. Ensure it is activated and has an appropriate data plan.
Plastic Cover Plate (Flush Device): Used as a base to mount the Beaglebone and other components, providing a compact and insulated housing for the device.
Rubber Bands: Simple yet effective for securing components to the plastic plate and managing wires, ensuring a robust and vibration-resistant assembly.
Optional Battery: A battery pack can provide backup power, ensuring continuous operation even if the OBDII power is temporarily disconnected or if the car battery fails. This is crucial for uninterrupted tracking and data logging in critical situations.

Assembling Your Beaglebone Black OBD2 Device: Step-by-Step

The assembly process for ChupaCarBrah is straightforward, requiring basic electronics knowledge and careful wiring. Follow these steps to build your device:

Prepare the Beaglebone for CAN Connection: Identify the CAN slot on your Beaglebone Black or Blue. The Beaglebone Blue pinout is shown for reference, highlighting the relevant CAN pins.

Pin configuration for Beaglebone Blue, emphasizing the CAN bus interface.
Connect the JST/SH Connector: Attach the JST/SH connector to the Beaglebone’s CAN slot. This connector serves as the interface between the Beaglebone and the hook-up wires leading to the OBDII connector.

Diagram illustrating the connection of the Beaglebone Blue CAN slot to the OBDII port.

Physically connecting the JST/SH connector to the Beaglebone CAN interface.
Wire the JST/SH Connector to Hook-up Wires: Connect the hook-up wires to the JST/SH connector. Adhere to the color code for consistency: Black (GND), Yellow (CAN High), and Green (CAN Low). In this project, Red wire is not used for CAN bus. Note that your JST/SH connector’s color standard might vary, so double-check your components.

Color coding for hook-up wires connecting to the JST/SH connector, specifying which wires are used for GND, CAN High and CAN Low.
- GND: JST/SH Black wire to Hook-up wire Black
- CAN Hi: JST/SH Yellow wire to Hook-up wire Yellow
- CAN Lo: JST/SH White wire to Hook-up wire Green
Connecting individual hook-up wires to the JST/SH connector for CAN communication.

Illustration highlighting that the red wire is intentionally not connected in this setup.
Connect Power via DC Barrel Jack Adapter: Prepare the DC Barrel Jack Adapter to power the Beaglebone from the OBDII port. Connect the black hook-up wire (GND) to the negative (-) slot and a red hook-up wire (12V) to the positive (+) slot. Since OBDII provides ground and 12V, you need to split the ground wire to connect both to the DC adapter and OBDII connector. Connect two black wires to the negative slot.

Connecting two black ground wires to the negative terminal of the DC Barrel Jack Adapter.

Connecting a red 12V wire to the positive terminal of the DC Barrel Jack Adapter.

The DC Barrel Jack Adapter and JST/SH connector are fully wired and ready for Beaglebone and OBDII connection.
Connect DC Barrel Jack to Beaglebone: Plug the DC Barrel Jack Adapter into the 12V input jack on the Beaglebone.

Powering the Beaglebone by connecting the DC Barrel Jack Adapter to its 12V input.
Wire Hook-up Wires to OBDII Connector: Connect the other ends of the hook-up wires to the female OBDII connector. Refer to the standard OBDII pinout diagram. Typically, OBDII pinouts are:
- Pin 5: Signal GND
- Pin 6: CAN High
- Pin 14: CAN Low
- Pin 16: 12V Power
Standard OBDII connector pinout diagram, indicating pins for ground, CAN bus, and power.

Connect the hook-up wires according to the color convention: Black wire to OBDII pin 5 (GND), Yellow wire to pin 6 (CAN High), Green wire to pin 14 (CAN Low), and Red wire to pin 16 (12V).

Connecting hook-up wires to the female OBDII connector, following the color-coded wiring convention.

The Beaglebone Black and OBDII connector are fully wired and connected, completing the core OBD2 interface.
Integrate GPS Module (Optional): If you’re including GPS functionality, connect the GPS module to the UART GPS slot on the Beaglebone.

Locating the UART GPS slot on the Beaglebone for GPS module integration.

Connecting the GPS module to the Beaglebone’s UART GPS slot.
Connect Cellular Modem (Optional): For cellular data connectivity, plug the USB cellular modem into a USB port on the Beaglebone. Ensure a SIM card is inserted into the modem before connecting.

Connecting the USB cellular modem, with a SIM card inserted, to the Beaglebone for network connectivity.
Mount Components: Attach the Beaglebone, GPS module, and optional battery to the plastic cover plate. Drill holes in the plate to match the Beaglebone mounting holes for secure attachment.

A plastic plate prepared with mounting holes to accommodate the Beaglebone and other components.

The Beaglebone mounted on the plastic cover plate, forming the base of the device assembly.
Secure GPS and Battery (Optional): Position the GPS module and battery (if used) at the bottom of the assembly for protection and stability.

Ensuring the GPS module is positioned securely at the bottom of the assembly for protection.

Placing the optional battery alongside the GPS module at the base of the assembly.
Final Assembly and Securing Wires: Place the OBDII cable over the battery and use rubber bands to secure all components to the plastic plate. Ensure hook-up wires are firmly connected to the OBDII connector and use additional rubber bands for extra security.

Positioning the OBDII cable over the battery within the assembly.

Using rubber bands to securely fasten all components together, creating a compact and robust device.

Additional rubber bands used to ensure the hook-up wires are securely connected to the OBDII connector.
Connect Battery (If Used) and Power On: If using a battery, connect it to the Beaglebone. Your ChupaCarBrah device is now assembled and ready to be powered on.

Final step of connecting the battery to power up the assembled Beaglebone device.

The completed ChupaCarBrah device powered on and ready for software configuration and data acquisition.

Software Setup for Beaglebone Black OBD2 Interface

With the hardware assembled, the next step is configuring the software on your Beaglebone Black to interact with the car’s CAN bus, GPS, and cellular network.

CAN Bus Communication with can-utils

Access your Beaglebone Black: Power on your Beaglebone Black and connect to it via WiFi. For remote operation, especially over cellular, WiFi is primarily used for initial setup and local testing.
Install can-utils: Ensure your system is up-to-date and install the can-utils package, which provides essential command-line tools for working with CAN bus.
```
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install can-utils
```
Verify CAN Interface (can0): Check if the can0 interface is available using ifconfig.
```
sudo ifconfig can0
```
A successful output will show can0 interface details, even if it’s currently down (disabled).
Disable can0 Interface: It’s recommended to disable the can0 interface before connecting to the car’s OBDII port.
```
sudo ifconfig can0 down
```
Connect ChupaCarBrah to OBDII Port: Locate the OBDII port in your vehicle (typically under the dashboard near the steering wheel) and plug in your ChupaCarBrah device.

Connecting the assembled ChupaCarBrah device to the vehicle’s OBDII port.

Close-up view of the vehicle’s OBDII port and the ChupaCarBrah OBDII connector.
Enable can0 Interface and Set Baud Rate: Turn on your car’s ignition (you may start the engine to prevent battery drain during testing). Set the CAN bus bitrate (typically 500kbps for OBDII) and bring the can0 interface up.
```
sudo ip link set can0 up type can bitrate 500000
sudo ifconfig can0 up
sudo ifconfig can0
```
Verify the output of the last command includes <UP>, indicating the interface is active.
Capture CAN Data with candump: Open a new terminal session and use candump to monitor CAN bus traffic.
```
sudo candump can0
```
You should see a stream of CAN messages if your vehicle actively broadcasts data on the CAN bus.
Send CAN Messages with cansend (if needed): Some vehicles have a quiet OBDII CAN bus that only responds to requests. To test CAN communication, use cansend to send a request for the Vehicle Identification Number (VIN). Keep candump running in the other terminal to see the response.
```
sudo cansend can0 7DF#0209020000000000
```
Look for responses in the candump output, particularly from ID 7E8. A valid response to the VIN request will contain part of the VIN.
Verify VIN Response: The response to the VIN request (service ID 9, PID 2) should contain hexadecimal encoded ASCII characters representing the VIN. Decode the relevant bytes from the candump output to verify. Online VIN decoders can be used to confirm the accuracy of the retrieved VIN.

Python CAN Interface with python-can

Install python-can: For Python-based CAN bus interaction, install the python-can library using pip.
```
sudo python3 -m pip install python-can
```
Run get_vin.py: Use the provided get_vin.py Python script to programmatically request and retrieve the VIN.
```
sudo python3 get_vin.py
```
This script demonstrates sending a CAN message and receiving a response using python-can.
Experiment with OBDII PIDs: Modify the get_vin.py script to explore other OBDII PIDs (Parameter IDs) to retrieve different vehicle parameters. Refer to OBDII PID documentation for available commands and service IDs.

GPS Data Retrieval

Test GPS Module with tio: Use the tio serial terminal tool to read raw GPS data from the GPS module connected to the Beaglebone’s UART.
```
tio /dev/ttyO2 -b 4800
```
You should see a stream of NMEA sentences, including $GPGGA and $GPRMC.
Interpret GPS Data: The $GPRMC sentence contains essential GPS information like latitude, longitude, speed, and time. Use online NMEA decoders to parse and visualize this data.

GPS coordinates from the module plotted on a map, demonstrating the location tracking capability.

Humorous image seemingly unrelated to the technical content, possibly a placeholder or mis-inserted image.

GPS coordinates visualized on Google Maps, further illustrating the accuracy of the GPS data.
Python GPS Data Retrieval with pyserial: Install the pyserial library and use the get_gps_data.py Python script to read and extract GPS data programmatically.
```
sudo python3 -m pip install pyserial
sudo python3 get_gps_data.py
```
This script reads serial data, extracts the $GPRMC sentence, and prints it.

Cellular Network Connectivity

Install PPP and Hologram Python SDK: If using a Hologram cellular modem (or similar PPP-based modem), install PPP and the Hologram Python SDK.
```
sudo apt-get install ppp
sudo python3 -m pip install hologram-python
```
Activate SIM Card: Ensure your Hologram SIM card (or the SIM for your chosen cellular provider) is activated and has a data plan. Refer to your provider’s documentation for activation steps.
Connect to Cellular Network: Use the Hologram CLI to connect to the cellular network.
```
sudo hologram network connect
```
Verify successful connection by checking modem LEDs (blue LED on, red LED blinking for Hologram modem).
Test Internet Connection: Ping a public website (e.g., Google) to confirm internet connectivity over cellular.
```
ping -c 1 www.google.com
```
Python Cellular Connection with cellular_test.py: Run the cellular_test.py Python script to programmatically manage cellular connections (connect and disconnect).
```
sudo python3 cellular_test.py
```

ChupaCarBrah Python Application: Client and Server

To bring all components together, the ChupaCarBrah project includes a client-server application for data exfiltration and remote monitoring.

Client Script (chupacarbrah.py)

Functionality: The chupacarbrah.py script runs on the Beaglebone Black. It reads OBDII PIDs from a CSV file, sends CAN requests, decodes responses, retrieves GPS data, and transmits all data to a server via cellular (or WiFi).
Configuration:
- obd2_csv_file: Specifies the CSV file containing OBDII PIDs to monitor. simple.csv and obd2_std_PIDs_enabled.csv are provided as examples.
- server_url: Sets the URL of the server application where data will be sent.
Operation:
1. Clones the ChupaCarBrah client script from GitHub:
```
git clone https://github.com/blupants/chupacarbrah.git
cd chupacarbrah
```
2. Runs the client script:
```
sudo python3 chupacarbrah.py
```
3. Stops the client gracefully by creating a /tmp/stop file:
```
sudo touch /tmp/stop
```

Server Script (chupacarbrah_server.py)

Functionality: The chupacarbrah_server.py is a Flask application designed to run on a server (e.g., AWS). It receives data from the ChupaCarBrah client and provides endpoints to store and view the received data in JSON format.
Endpoints:
- POST /api/v1/cars: Endpoint for the client to send car data.
- GET /api/v1/status: Endpoint to retrieve the latest car data in JSON format.
Local Testing:
1. Create a project directory eb-flask and a virtual environment virt.
2. Activate the virtual environment and install Flask.
3. Save chupacarbrah_server.py as application.py in the eb-flask directory.
4. Run the Flask application locally: python3 application.py.
5. Test data submission using curl to http://localhost:5000/api/v1/cars and view data at http://localhost:5000/api/v1/status.

AWS Deployment

AWS Account and Setup: Create an AWS account and install AWS CLI and EB CLI.
Initialize EB CLI: Navigate to the eb-flask directory and initialize an EB application: eb init -p python-3.6 flask-chupacarbrah --region us-east-2.
Configure SSH (Optional but Recommended): Configure SSH access to EC2 instances for debugging: eb init and choose to set up SSH.
Create EB Environment: Create an Elastic Beanstalk environment: eb create chupacarbrah-env. This process takes several minutes.
Open Web Application: Once the environment is ready, open your application in a browser: eb open.
Update Client Script: Copy the URL of your deployed AWS application and update the server_url variable in chupacarbrah.py on your Beaglebone Black.
Run Client and Monitor Data: Restart chupacarbrah.py on the Beaglebone. Data will now be transmitted to your AWS server and can be viewed by accessing the application URL in a browser.

Car Hacking and Further Exploration

This ChupaCarBrah project provides a solid starting point for car hacking and vehicle data analysis. With this device, you can:

Monitor Vehicle Performance: Track engine parameters, speed, temperature, and more in real-time.
Implement Telematics Applications: Develop fleet management, usage-based insurance, or vehicle tracking systems.
Explore Car Security: Investigate vehicle network security and potential vulnerabilities.
Customize Vehicle Interaction: Potentially send CAN messages to control vehicle functions (advanced and requires caution).

Stay tuned for further explorations into car hacking techniques and applications, building upon the foundation of the ChupaCarBrah device.