mirror of https://github.com/Qortal/Brooklyn
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
331 lines
9.8 KiB
331 lines
9.8 KiB
.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-3-Clause) |
|
|
|
can327: ELM327 driver for Linux SocketCAN |
|
========================================== |
|
|
|
Authors |
|
-------- |
|
|
|
Max Staudt <[email protected]> |
|
|
|
|
|
|
|
Motivation |
|
----------- |
|
|
|
This driver aims to lower the initial cost for hackers interested in |
|
working with CAN buses. |
|
|
|
CAN adapters are expensive, few, and far between. |
|
ELM327 interfaces are cheap and plentiful. |
|
Let's use ELM327s as CAN adapters. |
|
|
|
|
|
|
|
Introduction |
|
------------- |
|
|
|
This driver is an effort to turn abundant ELM327 based OBD interfaces |
|
into full fledged (as far as possible) CAN interfaces. |
|
|
|
Since the ELM327 was never meant to be a stand alone CAN controller, |
|
the driver has to switch between its modes as quickly as possible in |
|
order to fake full-duplex operation. |
|
|
|
As such, can327 is a best effort driver. However, this is more than |
|
enough to implement simple request-response protocols (such as OBD II), |
|
and to monitor broadcast messages on a bus (such as in a vehicle). |
|
|
|
Most ELM327s come as nondescript serial devices, attached via USB or |
|
Bluetooth. The driver cannot recognize them by itself, and as such it |
|
is up to the user to attach it in form of a TTY line discipline |
|
(similar to PPP, SLIP, slcan, ...). |
|
|
|
This driver is meant for ELM327 versions 1.4b and up, see below for |
|
known limitations in older controllers and clones. |
|
|
|
|
|
|
|
Data sheet |
|
----------- |
|
|
|
The official data sheets can be found at ELM electronics' home page: |
|
|
|
https://www.elmelectronics.com/ |
|
|
|
|
|
|
|
How to attach the line discipline |
|
---------------------------------- |
|
|
|
Every ELM327 chip is factory programmed to operate at a serial setting |
|
of 38400 baud/s, 8 data bits, no parity, 1 stopbit. |
|
|
|
If you have kept this default configuration, the line discipline can |
|
be attached on a command prompt as follows:: |
|
|
|
sudo ldattach \ |
|
--debug \ |
|
--speed 38400 \ |
|
--eightbits \ |
|
--noparity \ |
|
--onestopbit \ |
|
--iflag -ICRNL,INLCR,-IXOFF \ |
|
30 \ |
|
/dev/ttyUSB0 |
|
|
|
To change the ELM327's serial settings, please refer to its data |
|
sheet. This needs to be done before attaching the line discipline. |
|
|
|
Once the ldisc is attached, the CAN interface starts out unconfigured. |
|
Set the speed before starting it:: |
|
|
|
# The interface needs to be down to change parameters |
|
sudo ip link set can0 down |
|
sudo ip link set can0 type can bitrate 500000 |
|
sudo ip link set can0 up |
|
|
|
500000 bit/s is a common rate for OBD-II diagnostics. |
|
If you're connecting straight to a car's OBD port, this is the speed |
|
that most cars (but not all!) expect. |
|
|
|
After this, you can set out as usual with candump, cansniffer, etc. |
|
|
|
|
|
|
|
How to check the controller version |
|
------------------------------------ |
|
|
|
Use a terminal program to attach to the controller. |
|
|
|
After issuing the "``AT WS``" command, the controller will respond with |
|
its version:: |
|
|
|
>AT WS |
|
|
|
|
|
ELM327 v1.4b |
|
|
|
> |
|
|
|
Note that clones may claim to be any version they like. |
|
It is not indicative of their actual feature set. |
|
|
|
|
|
|
|
|
|
Communication example |
|
---------------------- |
|
|
|
This is a short and incomplete introduction on how to talk to an ELM327. |
|
It is here to guide understanding of the controller's and the driver's |
|
limitation (listed below) as well as manual testing. |
|
|
|
|
|
The ELM327 has two modes: |
|
|
|
- Command mode |
|
- Reception mode |
|
|
|
In command mode, it expects one command per line, terminated by CR. |
|
By default, the prompt is a "``>``", after which a command can be |
|
entered:: |
|
|
|
>ATE1 |
|
OK |
|
> |
|
|
|
The init script in the driver switches off several configuration options |
|
that are only meaningful in the original OBD scenario the chip is meant |
|
for, and are actually a hindrance for can327. |
|
|
|
|
|
When a command is not recognized, such as by an older version of the |
|
ELM327, a question mark is printed as a response instead of OK:: |
|
|
|
>ATUNKNOWN |
|
? |
|
> |
|
|
|
At present, can327 does not evaluate this response. See the section |
|
below on known limitations for details. |
|
|
|
|
|
When a CAN frame is to be sent, the target address is configured, after |
|
which the frame is sent as a command that consists of the data's hex |
|
dump:: |
|
|
|
>ATSH123 |
|
OK |
|
>DEADBEEF12345678 |
|
OK |
|
> |
|
|
|
The above interaction sends the SFF frame "``DE AD BE EF 12 34 56 78``" |
|
with (11 bit) CAN ID ``0x123``. |
|
For this to function, the controller must be configured for SFF sending |
|
mode (using "``AT PB``", see code or datasheet). |
|
|
|
|
|
Once a frame has been sent and wait-for-reply mode is on (``ATR1``, |
|
configured on ``listen-only=off``), or when the reply timeout expires |
|
and the driver sets the controller into monitoring mode (``ATMA``), |
|
the ELM327 will send one line for each received CAN frame, consisting |
|
of CAN ID, DLC, and data:: |
|
|
|
123 8 DEADBEEF12345678 |
|
|
|
For EFF (29 bit) CAN frames, the address format is slightly different, |
|
which can327 uses to tell the two apart:: |
|
|
|
12 34 56 78 8 DEADBEEF12345678 |
|
|
|
The ELM327 will receive both SFF and EFF frames - the current CAN |
|
config (``ATPB``) does not matter. |
|
|
|
|
|
If the ELM327's internal UART sending buffer runs full, it will abort |
|
the monitoring mode, print "BUFFER FULL" and drop back into command |
|
mode. Note that in this case, unlike with other error messages, the |
|
error message may appear on the same line as the last (usually |
|
incomplete) data frame:: |
|
|
|
12 34 56 78 8 DEADBEEF123 BUFFER FULL |
|
|
|
|
|
|
|
Known limitations of the controller |
|
------------------------------------ |
|
|
|
- Clone devices ("v1.5" and others) |
|
|
|
Sending RTR frames is not supported and will be dropped silently. |
|
|
|
Receiving RTR with DLC 8 will appear to be a regular frame with |
|
the last received frame's DLC and payload. |
|
|
|
"``AT CSM``" (CAN Silent Monitoring, i.e. don't send CAN ACKs) is |
|
not supported, and is hard coded to ON. Thus, frames are not ACKed |
|
while listening: "``AT MA``" (Monitor All) will always be "silent". |
|
However, immediately after sending a frame, the ELM327 will be in |
|
"receive reply" mode, in which it *does* ACK any received frames. |
|
Once the bus goes silent, or an error occurs (such as BUFFER FULL), |
|
or the receive reply timeout runs out, the ELM327 will end reply |
|
reception mode on its own and can327 will fall back to "``AT MA``" |
|
in order to keep monitoring the bus. |
|
|
|
Other limitations may apply, depending on the clone and the quality |
|
of its firmware. |
|
|
|
|
|
- All versions |
|
|
|
No full duplex operation is supported. The driver will switch |
|
between input/output mode as quickly as possible. |
|
|
|
The length of outgoing RTR frames cannot be set. In fact, some |
|
clones (tested with one identifying as "``v1.5``") are unable to |
|
send RTR frames at all. |
|
|
|
We don't have a way to get real-time notifications on CAN errors. |
|
While there is a command (``AT CS``) to retrieve some basic stats, |
|
we don't poll it as it would force us to interrupt reception mode. |
|
|
|
|
|
- Versions prior to 1.4b |
|
|
|
These versions do not send CAN ACKs when in monitoring mode (AT MA). |
|
However, they do send ACKs while waiting for a reply immediately |
|
after sending a frame. The driver maximizes this time to make the |
|
controller as useful as possible. |
|
|
|
Starting with version 1.4b, the ELM327 supports the "``AT CSM``" |
|
command, and the "listen-only" CAN option will take effect. |
|
|
|
|
|
- Versions prior to 1.4 |
|
|
|
These chips do not support the "``AT PB``" command, and thus cannot |
|
change bitrate or SFF/EFF mode on-the-fly. This will have to be |
|
programmed by the user before attaching the line discipline. See the |
|
data sheet for details. |
|
|
|
|
|
- Versions prior to 1.3 |
|
|
|
These chips cannot be used at all with can327. They do not support |
|
the "``AT D1``" command, which is necessary to avoid parsing conflicts |
|
on incoming data, as well as distinction of RTR frame lengths. |
|
|
|
Specifically, this allows for easy distinction of SFF and EFF |
|
frames, and to check whether frames are complete. While it is possible |
|
to deduce the type and length from the length of the line the ELM327 |
|
sends us, this method fails when the ELM327's UART output buffer |
|
overruns. It may abort sending in the middle of the line, which will |
|
then be mistaken for something else. |
|
|
|
|
|
|
|
Known limitations of the driver |
|
-------------------------------- |
|
|
|
- No 8/7 timing. |
|
|
|
ELM327 can only set CAN bitrates that are of the form 500000/n, where |
|
n is an integer divisor. |
|
However there is an exception: With a separate flag, it may set the |
|
speed to be 8/7 of the speed indicated by the divisor. |
|
This mode is not currently implemented. |
|
|
|
- No evaluation of command responses. |
|
|
|
The ELM327 will reply with OK when a command is understood, and with ? |
|
when it is not. The driver does not currently check this, and simply |
|
assumes that the chip understands every command. |
|
The driver is built such that functionality degrades gracefully |
|
nevertheless. See the section on known limitations of the controller. |
|
|
|
- No use of hardware CAN ID filtering |
|
|
|
An ELM327's UART sending buffer will easily overflow on heavy CAN bus |
|
load, resulting in the "``BUFFER FULL``" message. Using the hardware |
|
filters available through "``AT CF xxx``" and "``AT CM xxx``" would be |
|
helpful here, however SocketCAN does not currently provide a facility |
|
to make use of such hardware features. |
|
|
|
|
|
|
|
Rationale behind the chosen configuration |
|
------------------------------------------ |
|
|
|
``AT E1`` |
|
Echo on |
|
|
|
We need this to be able to get a prompt reliably. |
|
|
|
``AT S1`` |
|
Spaces on |
|
|
|
We need this to distinguish 11/29 bit CAN addresses received. |
|
|
|
Note: |
|
We can usually do this using the line length (odd/even), |
|
but this fails if the line is not transmitted fully to |
|
the host (BUFFER FULL). |
|
|
|
``AT D1`` |
|
DLC on |
|
|
|
We need this to tell the "length" of RTR frames. |
|
|
|
|
|
|
|
A note on CAN bus termination |
|
------------------------------ |
|
|
|
Your adapter may have resistors soldered in which are meant to terminate |
|
the bus. This is correct when it is plugged into a OBD-II socket, but |
|
not helpful when trying to tap into the middle of an existing CAN bus. |
|
|
|
If communications don't work with the adapter connected, check for the |
|
termination resistors on its PCB and try removing them.
|
|
|