-Linux SocketCAN driver for ELM327
-==================================
+.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-3-Clause)
+
+can327: ELM327 driver for Linux SocketCAN
+==========================================
+
+Out-of-tree version
+--------------------
+
+This is the non-upstreamed version of the can327 driver.
+Please see out-of-tree.rst for compilation/usage hints.
+
+
Authors
--------
-Max Staudt <elmcan@enpas.org>
+Max Staudt <max-linux@enpas.org>
Motivation
-----------
-CAN adapters are expensive, few, and far between.
-ELM327 interfaces are cheap and plentiful.
-
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.
+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 asa quickly as possible in
-order to approximate full-duplex operation.
+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, elmcan is a best-effort driver. However, this is more than
+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).
-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
-
- >
-
-
-
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.
-The line discipline can be attached on a command prompt as follows::
+If you have kept this default configuration, the line discipline can
+be attached on a command prompt as follows::
sudo ldattach \
--debug \
--noparity \
--onestopbit \
--iflag -ICRNL,INLCR,-IXOFF \
- 26 \
+ 29 \
/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
-Known limitations of the controller
-------------------------------------
-
-- All versions
-
- No automatic 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
+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.
- 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 elmcan. They do not support
- the "``AT D1``", 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.
+After this, you can set out as usual with candump, cansniffer, etc.
-Known limitations of the driver
---------------------------------
+How to check the controller version
+------------------------------------
-- No 8/7 timing.
+Use a terminal program to attach to the controller.
- 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.
+After issuing the "``AT WS``" command, the controller will respond with
+its version::
-- No evaluation of command responses.
+ >AT WS
- 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
+ ELM327 v1.4b
- 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.
+ >
-- No BUS-OFF state and automatic restart
+Note that clones may claim to be any version they like.
+It is not indicative of their actual feature set.
- We currently reset the ELM327 and generate error frames manually.
- In the future, we may be able to use ``can_bus_off()`` and its siblings.
----------------------
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:
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 elmcan.
+for, and are actually a hindrance for can327.
When a command is not recognized, such as by an older version of the
?
>
-At present, elmcan does not evaluate this response and silently assumes
+At present, can327 does not evaluate this response and silently assumes
that all commands are recognized. It is structured such that it will
degrade gracefully when a command is unknown. See the sections above on
known limitations for details.
OK
>
-The above interaction sends the frame "``DE AD BE EF 12 34 56 78``" with
-the 11 bit CAN ID ``0x123``.
-For this to function, the controller must be configured for 11 bit CAN
-ID sending mode (using "``AT PB``", see code or datasheet).
+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::
+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 29 bit CAN frames, the address format is slightly different, which
-elmcan uses to tell the two apart::
+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 11 and 29 bit frames - the current CAN
+The ELM327 will receive both SFF and EFF frames - the current CAN
config (``ATPB``) does not matter.
-To Do list for future development
-----------------------------------
+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
-- Handle ``write()`` error
+ We need this to distinguish 11/29 bit CAN addresses received.
-- Rename ``elm327_panic()``
+ 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).
-- No auto-restart in ``elm327_panic()``?
+``AT D1``
+ DLC on
-- Stop current function when in ``elm327_panic()``
+ We need this to tell the "length" of RTR frames.
-- ``if (!elm)``: Race with ``ldisc_close()``
-- ``elm->dev``: Race in ``ldisc_ioctl()``
-- DMA capable rx/tx buffers
+A note on CAN bus termination
+------------------------------
-- fixup constants, constant for '``>``'
+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.
-- flushing of ``tx_work`` is too late in ``ldisc_close()``
+If communications don't work with the adapter connected, check for the
+termination resistors on its PCB and try removing them.
projects / elmcan.git / blobdiff