.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-3-Clause)
-ELM327 driver for Linux SocketCAN
-==================================
+can327: ELM327 driver for Linux SocketCAN
+==========================================
+
+Upstream
+--------
+
+This driver has become an official part of Linux since v6.0:
+
+ https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/drivers/net/can/can327.c?h=v6.0
+
+For documentation and how to use the driver, please refer to the
+documentation that comes with your Linux kernel version, since
+the details may change as the driver evolves. The documentation
+below applies ONLY to the downstream driver.
+
+ https://www.kernel.org/doc/html/latest/networking/device_drivers/can/can327.html
+
+Please send patches upstream to [linux-can] and the maintainers for
+this driver.
+
+I may or may not backport upstream patches to this downstream
+repository, and/or use it for further pre-upstream work.
+
+
Out-of-tree version
--------------------
-This is the non-upstreamed version of the elmcan driver.
+This is the non-upstreamed version of the can327 driver.
Please see out-of-tree.rst for compilation/usage hints.
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.
-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::
-
- >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.
-
-
-
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 \
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:
+Set the speed before starting it::
# The interface needs to be down to change parameters
sudo ip link set can0 down
+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
------------------------------------
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``"
+ "``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
- Versions prior to 1.3
- These chips cannot be used at all with elmcan. They do not support
+ 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.
-Communication example
-----------------------
-
-This is a short and incomplete introduction on how to talk to an ELM327.
-
-
-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 elmcan.
-
-
-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, elmcan 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.
-
-
-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 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).
-
-
-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::
-
- 12 34 56 78 8 DEADBEEF12345678
-
-The ELM327 will receive both 11 and 29 bit 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
-
-
-
Rationale behind the chosen configuration
------------------------------------------
projects / elmcan.git / blobdiff