-Linux SocketCAN driver for ELM327
+ELM327 driver for Linux SocketCAN
==================================
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, elmcan 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).
+Requirements
+-------------
+
+This requires Linux 4.11 (for 431af779256c), and has been tested on 4.19.
+
+Also, elmcan depends on ``can-dev``:
+
+ sudo modprobe can-dev
+
+Install
+-------------
+ cd module/
+
+ sudo dkms install .
+
Data sheet
-----------
------------------------------------
Use a terminal program to attach to the controller.
+The default settings are 38400 baud/s, 8 data bits, no parity, 1 stopbit.
After issuing the "``AT WS``" command, the controller will respond with
its version::
>
+Note that clones may claim to be any version they like.
+It is not indicative of their actual feature set.
+
How to attach the line discipline
--noparity \
--onestopbit \
--iflag -ICRNL,INLCR,-IXOFF \
- 26 \
+ 29 \
/dev/ttyUSB0
To change the ELM327's serial settings, please refer to its data
+Module parameters
+------------------
+
+- ``accept_flaky_uart`` - Try to live with a bad controller or UART line
+
+ Some adapters and/or their connection are unreliable. Enable this
+ option to try and work around the situation. This is a best effort
+ workaround, so undefined behavior will likely occur sooner or later.
+ Without this option, the driver will bail on the first unrecognized
+ character it receives from the TTY.
+
+ LOAD TIME::
+
+ module/kernel parameter: accept_flaky_uart=[0|1]
+
+
+
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``" not supported, thus no ACK-ing frames while listening:
+ "``AT MA``" 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), the ELM327 will end reply
+ reception mode on its own and elmcan will fall back to "``AT MA``"
+ in order to keep monitoring the bus.
+
+
- All versions
- No automatic full duplex operation is supported. The driver will
- switch between input/output mode as quickly as possible.
+ 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
helpful here, however SocketCAN does not currently provide a facility
to make use of such hardware features.
-- No BUS-OFF state and automatic restart
-
- 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.
-
Communication example
ID 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
+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::
-To Do list for future development
-----------------------------------
+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.
+
-- No auto-restart in ``elm327_panic()``?
-- Stop current function when in ``elm327_panic()``
+Thanks
+-------
-- DMA capable rx/tx buffers
+Thanks go out to Oliver Neukum for his early reviews and suggestions.
-- flushing of ``tx_work`` is too late in ``ldisc_close()``
+Several more people have encouraged me to finish this - thank you all.
projects / elmcan.git / blobdiff