/VanBus

Vehicle Area Network (VAN) bus packet reader/writer

Primary LanguageC++MIT LicenseMIT

PSA (Peugeot, Citroën) VAN bus reader/writer for Arduino-ESP8266

Reading and writing packets from/to PSA vehicles' VAN bus.

📝 Table of Contents

🎈 Description

This module allows you to receive and transmit packets on the "VAN" bus of your Peugeot or Citroen vehicle.

VAN bus is pretty similar to CAN bus. It was used in many cars (Peugeot, Citroen) made by PSA.

In the beginning of 2000's the PSA group (Peugeot and Citroen) used VAN bus as a communication protocol between the various comfort-related equipment. Later, around 2005, they started to replace this protocol in their newer cars with the CAN bus protocol, however some models had VAN bus inside them until 2009.

Only ESP8266 / ESP8285 is supported. ESP32 is NOT supported by this library; for boards with those MCUs there is this excellent library: ESP32 RMT peripheral Vehicle Area Network (VAN bus) reader.

🔌 Schematics

You can usually find the VAN bus on pins 2 and 3 of ISO block "A" of your head unit (car radio). See https://en.wikipedia.org/wiki/Connectors_for_car_audio and https://github.com/morcibacsi/esp32_rmt_van_rx#schematics .

There are various possibilities to hook up a ESP8266 based board to your vehicle's VAN bus:

  1. Use a MCP2551 transceiver, connected with its CANH and CANL pins to the vehicle's VAN bus. As the MCP2551 has 5V logic, a 5V ↔ 3.3V level converter is needed to connect the CRX / RXD / R pin of the transceiver, via the level converter, to a GPIO pin of your ESP8266 board. For transmitting packets, also connect the CTX / TXD / D pins of the transceiver, via the level converter, to a GPIO pin of your ESP8266 board.

schema

👉 Note: CANH of the transceiver is connected to VAN BAR, CANL to VAN. This may seem illogical but in practice it turns out this works best.

  1. Use a SN65HVD230 transceiver, connected with its CANH and CANL pins to the vehicle's VAN bus. The SN65HVD230 transceiver already has 3.3V logic, so it is possible to directly connect the CRX / RXD / R pin of the transceiver to a GPIO pin of your ESP8266 board. For transmitting packets, also connect the CTX / TXD / D pins of the transceiver to a GPIO pin of your ESP8266 board.

schema

👉 Note: CANH of the transceiver is connected to VAN BAR, CANL to VAN. This may seem illogical but in practice it turns out this works best.

  1. The simplest schematic is not to use a transceiver at all, but connect the VAN DATA line to GrouND using two 4.7 kOhm resistors. Connect the GPIO pin of your ESP8266 board to the 1:2 voltage divider that is thus formed by the two resistors. This is only for receiving packets, not for transmitting. Results may vary.

schema

👉 Note: I used this schematic during many long debugging hours, but I cannot guarantee that it won't ultimately cause your car to explode! (or anything less catastrofic)

🚀 Usage

General

Add the following line to your .ino sketch:

#include <VanBus.h>

For receiving and transmitting packets:

  1. Add the following lines to your initialisation block void setup():
int TX_PIN = D3; // Set to GPIO pin connected to VAN bus transceiver input
int RX_PIN = D2; // Set to GPIO pin connected to VAN bus transceiver output
TVanBus::Setup(RX_PIN, TX_PIN);
  1. Add e.g. the following lines to your main loop void loop():
TVanPacketRxDesc pkt;
if (VanBus.Receive(pkt)) pkt.DumpRaw(Serial);

uint8_t rmtTemperatureBytes[] = {0x0F, 0x07, 0x00, 0x00, 0x00, 0x00, 0x70};
VanBus.SyncSendPacket(0x8A4, 0x08, rmtTemperatureBytes, sizeof(rmtTemperatureBytes));

If you only want to receive packets, you may save a few hundred precious bytes by using directly the VanBusRx object:

  1. Add the following lines to your initialisation block void setup():
int RX_PIN = D2; // Set to GPIO pin connected to VAN bus transceiver output
VanBusRx.Setup(RX_PIN);
  1. Add the following lines to your main loop void loop():
TVanPacketRxDesc pkt;
if (VanBusRx.Receive(pkt)) pkt.DumpRaw(Serial);

VanBus object

The following methods are available for the VanBus object:

Interfaces for both receiving and transmitting of packets:

  1. void Setup(uint8_t rxPin, uint8_t txPin)
  2. void DumpStats(Stream& s)

Interfaces for receiving packets:

  1. bool Available()
  2. bool Receive(TVanPacketRxDesc& pkt, bool* isQueueOverrun = NULL)
  3. uint32_t GetRxCount()

Interfaces for transmitting packets:

  1. bool SyncSendPacket(uint16_t iden, uint8_t cmdFlags, const uint8_t* data, size_t dataLen, unsigned int timeOutMs = 10)
  2. bool SendPacket(uint16_t iden, uint8_t cmdFlags, const uint8_t* data, size_t dataLen, unsigned int timeOutMs = 10)
  3. uint32_t GetTxCount()

1. void Setup(uint8_t rxPin, uint8_t txPin)

Start the receiver listening on GPIO pin rxPin. The transmitter will transmit on GPIO pin txPin.

2. void DumpStats(Stream& s)

Dumps a few packet statistics on the passed stream.

3. bool Available()

Returns true if a VAN packet is available in the receive queue.

4. bool Receive(TVanPacketRxDesc& pkt, bool* isQueueOverrun = NULL)

Copy a VAN packet out of the receive queue, if available. Otherwise, returns false. If a valid pointer is passed to 'isQueueOverrun', will report then clear any queue overrun condition.

5. uint32_t GetRxCount()

Returns the number of received VAN packets since power-on. Counter may roll over.

6. bool SyncSendPacket(uint16_t iden, uint8_t cmdFlags, const uint8_t* data, size_t dataLen, unsigned int timeOutMs = 10)

Sends a packet for transmission. Returns true if the packet was successfully transmitted.

7. bool SendPacket(uint16_t iden, uint8_t cmdFlags, const uint8_t* data, size_t dataLen, unsigned int timeOutMs = 10)

Queues a packet for transmission. Returns true if the packet was successfully queued.

8. uint32_t GetTxCount()

Returns the number of VAN packets, offered for transmitting, since power-on. Counter may roll over.

VAN packets

On a VAN bus, the electrical signals are the same as CAN. However, CAN and VAN use different data encodings on the line which makes it impossible to use CAN interfaces on a VAN bus.

For background reading:

The following methods are available for TVanPacketRxDesc packet objects as obtained from VanBusRx.Receive(...):

  1. uint16_t Iden()
  2. uint16_t CommandFlags()
  3. const uint8_t* Data()
  4. int DataLen()
  5. uint16_t Crc()
  6. bool CheckCrc()
  7. bool CheckCrcAndRepair()
  8. void DumpRaw(Stream& s, char last = '\n')
  9. const TIsrDebugPacket& getIsrDebugPacket()
  10. const char* CommandFlagsStr()
  11. const char* AckStr()
  12. const char* ResultStr()

1. uint16_t Iden()

Returns the IDEN field of the VAN packet.

An overview of known IDEN values can be found e.g. at:

2. uint16_t CommandFlags()

Returns the "command" FLAGS field of the VAN packet. Each VAN packet has 4 "command" flags:

  • EXT : always 1
  • RAK : 1 = Requesting AcKnowledge
  • R/W : 1 = Read operation, 0 = Write operation
  • RTR : 1 = Remote Transmit Request

A thorough explanation is found (in French) on page 6 and 7 of http://www.educauto.org/files/file_fields/2013/11/18/mux3.pdf#page=6 .

3. const uint8_t* Data()

Returns the data field (bytes) of the VAN packet.

4. int DataLen()

Returns the number of data bytes in the VAN packet. There can be at most 28 data bytes in a VAN packet.

5. unsigned long Millis()

Packet time stamp in milliseconds.

6. uint16_t Crc()

Returns the 15-bit CRC value of the VAN packet.

7. bool CheckCrc()

Checks the CRC value of the VAN packet.

8. bool CheckCrcAndRepair()

Checks the CRC value of the VAN packet. If not, tries to repair it by flipping each bit. Returns true if the packet is OK (either before or after the repair).

9. void DumpRaw(Stream& s, char last = '\n')

Dumps the raw packet bytes to a stream. Optionally specify the last character; default is '\n' (newline).

Example of invocation:

pkt.DumpRaw(Serial);

Example of output:

Raw: #0002 ( 2/15) 11(16) 0E 4D4 RA0 82-0C-01-00-11-00-3F-3F-3F-3F-82:7B-A4 ACK OK 7BA4 CRC_OK

Example of dumping into a char array:

const char* PacketRawToStr(TVanPacketRxDesc& pkt)
{
    static char dumpBuffer[MAX_DUMP_RAW_SIZE];
    
    GString str(dumpBuffer);
    PrintAdapter streamer(str);
    pkt.DumpRaw(streamer, '\0');
    
    return dumpBuffer;
}

Note: for this, you will need to install the PrintEx library. I tested with version 1.2.0 .

10. const TIsrDebugPacket& getIsrDebugPacket()

Retrieves a debug structure that can be used to analyse (observed) bit timings.

11. const char* CommandFlagsStr()

Returns the "command" FLAGS field of the VAN packet as a string

Note: uses a statically allocated buffer, so don't call this method twice within the same printf invocation.

12. const char* AckStr()

Returns the ACK field of the VAN packet as a string, either "ACK" or "NO_ACK".

13. const char* ResultStr()

Returns the RESULT field of the VAN packet as a string, either "OK" or a string starting with "ERROR_".

⚠️ Limitations, Caveats

The library times the incoming bits using an interrupt service routine (ISR) that triggers on pin "change" events (see the internal function RxPinChangeIsr in VanBusRx.cpp).

When Wi-Fi is enabled, the invocation of the ISR is often quite late (even if there is no Wi-Fi connection active). It turns out that disabling Wi-Fi altogether is the way to get a completely error-free packet reception, like this:

15:10:26.335 -> received pkts: 104883, corrupt: 0 (0.000%), repaired: 0 (---%), overall: 0 (0.000%)

With Wi-Fi enabled, not all VAN bus packets are received error-free. Even after trying to "repair" a packet (see function bool CheckCrcAndRepair()), the long-term average packet loss is around 0.01% ... 0.015% (between 1 in 10,000 and 1 in 6,666), which is pretty workable for most applications. I am investigating how to improve on this.

👷 Work to be Done

Near future

Currently the library supports only 125 kbit/s VAN bus. Need to add support for different rate, like 62.5 kbit/s, which can be passed as an optional parameter to VanBusRx.Setup(...).

📖 License

This library is open-source and licensed under the MIT license.

Do whatever you like with it, but contributions are appreciated!

See also

  • VAN Live Connect - Live data from your PSA vehicle (Peugeot, Citroën) on your smartphone or tablet, directly from the VAN bus.