PHP-CanBus Extension

PHP-canbus is THE extension for PHP on Linux that allows PHP code to interface efficiently with a Controller Area Network (CAN bus) 2.0A / 2.0B.

Due to the CAN Frames lightweight nature (they consist only of 11 or 29 bit identifier, 0 to 8 data bytes and flags) using methods like parsing shell_exec('candump vcan0 -n 1') output has huge drawbacks - it supports only blocking mode and is really really slow. Performance is often a key aspect as most use-cases of CAN-Bus is in embedded systems. With this extension you can efficiently control your car, elevator or even airplane.

Development and testing was done on Ubuntu 20.04 with VCAN, real world tests performed on Raspberry Pi 4B + MCP2515+TJA1050 module.

Table of content

• Basics
  • Classes & methods
  • Examples
• Building
• Installation
• TODOs
• Links

Basics

Classes and methods

class CanBus {

    /**
     * CanBus constructor.
     *
     * @param string $interface non-empty string
     */
    public function __construct(string $interface) {}

    /**
     * Initializes CanBus interface and connects to unix sockets
     * If socket was initialized before, it closes previous connection
     *
     * @param bool $blocking Whether interface should be blocking or not
     * @return bool success/failure
     */
    public function init(bool $blocking = true): bool {}

    /**
     * Attempts to read single CanFrame.
     *
     * @return CanFrame|false CanFrame on success, false on failure
     */
    public function read(): CanFrame|false {}
    
    /**
     * Attempts to send single CanFrame.
     *
     * @return bool success/failure
     */
    public function send(CanFrame $frame): bool {}

    /**
     * Generates random CanFrame
     * ID: 0 to 0x7FF
     * Data: 0 to 8 bytes of values in range of 0 to 0xFF (0-255)
     *
     * @return CanFrame
     */
    public function generateRandomFrame(): CanFrame {}
}

class CanFrame {

    /**
     * CanFrame constructor.
     *
     * @param int $index value in range o 0 to 0x7FFFFFFF (CAN 2.0B)
     * @param array $data 0 to 8 bytes of values in range of 0 to 0xFF (0-255)
     */
    public function __construct(int $index, array $data) {}
}

Examples

Listening:

<?php

// Create new CanBus interface object
$canBus = new CanBus('vcan0');

// Initialize interface (connect to unix socket)
if($canBus->init() === false) {
    // Handle error
}

// Read loop
while(true) {
    $frame = $canBus->read();
    if($frame === false) continue;
    
    // Do something with the frame
}

Sending:

<?php

// Create new CanBus interface object
$canBus = new CanBus('vcan0');

// Initialize interface (connect to unix socket)
if($canBus->init() === false) {
    // Handle error
}

// Create new frame
$canFrame = new CanFrame(
    0x204,
    [0x00, 0x02, 0x01]
);

// Send new frame
if($canBus->send($canFrame) === false) {
    // Handle error
}

Testing:

<?php

// Create new CanBus interface object
$canBus = new CanBus('vcan0');

// Generate random frame
$randomCanFrame = $canBus->generateRandomFrame();
var_dump($randomCanFrame);

// Create new frame
$canFrame = new CanFrame(
    0x204, // Id
    [0x00, 0x02, 0x01, 0x00, 0x00, 0x00, 0x00, 0x08] // Data
);
var_dump($canFrame);

Building

Download latest php-dev package (as the time of writing: sudo apt install php8.2-dev).

Then run following commands inside repo directory:

phpize              # configures extension for your PHP version
./configure         # configures extension details
make                # builds extension
make install        # installs extension in your system

Installation

• Find out path to your php.ini file by running php -i | grep "Configuration File (php.ini) Path"
  • It should be something like /etc/php/8.0/cli
• Open php.ini file it in text editor (ex. sudo nano /etc/php/8.0/cli/php.ini)
  • As it might be in write-restricted path, use sudo
• Find Dynamic Extensions section (around line 900)
• If you previously used make install, add line extension=canbus
  • Otherwise, add extension=/home/pi/canbus.so where /home/pi/canbus.so is an extension path

TODOs

• Extension skeleton
• Connecting to unix socket
• Listening
  • Blocking
  • Non-blocking
  • Socket-based filtering
• Sending
• More detailed tests
• Ensure no memory leaks
• CAN-FD Support
• CI for different PHP versions

Links

• CAN-Bus wikipedia
• Linux CAN utils
• Raspberry PI + MCP2515, Polish guide
• How to write PHP exntesion by ZEND
• PHP extension whitepaper
• PHP internals book
• PHP Fast Parameter Parsing API RFC From 2014, included in PHP 7.x (2015+)
• 2011 PHP extension guide, Archive (uses old parameter parsing api)
• Archive: 2005 PHP extension guide (uses old parameter parsing api)
• Archive: PHP Documentation on internals