Skip to content

Commit

Permalink
Updated documentation for the acf-can-bridge.
Browse files Browse the repository at this point in the history 
Signed-off-by: Naresh Nayak <[email protected]>
  • Loading branch information
@nayakned @SebastianSchildt
nayakned authored and SebastianSchildt committed Dec 18, 2024
1 parent 170accc commit c0cf41d
Show file tree
Hide file tree
Showing 3 changed files with 83 additions and 23 deletions.
96 changes: 78 additions & 18 deletions examples/acf-can/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,67 +1,106 @@
# ACF-CAN Applications

The two applications available in this folder are acf-can-listener and acf-can-talker. These applications can be used along with Linux CAN utilities. On Ubuntu/Debian Linux distributions, these utilities can be installed using the package manager `apt install can-utils`
Following applications are available in this folder:
- _acf-can-listener_: Parses received IEEE 1722 ACF frames and puts our the encapsulated CAN/CAN-FD frames onto the CAN bus
- _acf-can-talker_: Creates IEEE 1722 ACF frames out of received CAN frames and sends them out on the network interface
- _acf-can-bridge_: Combines the _acf-can-talker_ and _acf-can-listener_ to create a two way bridge between a CAN interface and an Ethernet network interface

All these applications support IEEE 1722 over Ethernet (layer 2) as well as over UDP (layer 4).
These applications can be used along with Linux CAN utilities. On Ubuntu/Debian Linux distributions, these utilities can be installed using the package manager `apt install can-utils`

## acf-can-talker
_acf-can-talker_ receives frames on a (virtual) CAN interface and sends out the corresponding IEEE 1722 ACF messages. This application also supports UDP encapsulation for the IEEE 1722 messages. The parameters for its usage are as follows:
_acf-can-talker_ receives frames on a (virtual) CAN interface and sends out the corresponding IEEE 1722 ACF messages. The parameters for its usage are as follows:

```
Usage: acf-can-talker [OPTION...]
acf-can-talker -- a program designed to send CAN messages to a remote CAN bus
over Ethernet using Open1722.
acf-can-talker -- a program to send CAN messages to a remote CAN bus over
Ethernet using Open1722.
--canif CAN interface
--canif=CAN_IF CAN interface
-c, --count=COUNT Set count of CAN messages per Ethernet frame
-d, --dst-addr=MACADDR Stream destination MAC address (If Ethernet)
--fd Use CAN-FD
-i, --ifname Network interface (If Ethernet)
-n, --dst-nw-addr Stream destination network address and port (If
-i, --ifname=IFNAME Network interface (If Ethernet)
-n, --dst-nw-addr=NW_ADDR Stream destination network address and port (If
UDP)
-t, --tscf Use TSCF
-u, --udp Use UDP
--stream-id=STREAM_ID Stream ID for talker stream
-t, --tscf Use TSCF (Default: NTSCF)
-u, --udp Use UDP (Default: Ethernet)
-?, --help Give this help list
--usage Give a short usage message
```

## acf-can-talker
_acf-can-listener_ receives IEEE 1722 ACF messages and puts out the corresponding CAN frames on a (virtual) CAN interface. Analogous to the _acf_can_talker_, UDP encapsulation is also available for this application. The parameters for its usage are as follows:
_acf-can-listener_ receives IEEE 1722 ACF messages and puts out the corresponding CAN frames on a (virtual) CAN interface. The parameters for its usage are as follows:

```
Usage: acf-can-listener [OPTION...]
acf-can-listener -- a program designed to receive CAN messages from a remote
CAN bus over Ethernet using Open1722.
--canif CAN interface
--canif=CAN_IF CAN interface
-d, --dst-addr=MACADDR Stream destination MAC address (If Ethernet)
--fd Use CAN-FD
-i, --ifname Network interface (If Ethernet)
-p, --udp-port UDP Port to listen on (if UDP)
-u, --udp Use UDP
-i, --ifname=IFNAME Network interface (If Ethernet)
-p, --udp-port=UDP_PORT UDP Port to listen on (if UDP)
--stream-id=STREAM_ID Stream ID for listener stream
-u, --udp Use UDP (Default: Ethernet)
-?, --help Give this help list
--usage Give a short usage message
```

## Quickstart Tutorial: Tunneling CAN over IEEE 1722 using Linux CAN utilities
## acf-can-bridge
_acf-can-bridge_ bridges the Ethernet domain with the CAN domain, i.e., all received IEEE 1722 ACF frames will be parsed for extracting CAN frames which will be sent out on CAN bus and all received CAN frames will be packed into IEEE 1722 ACF messages and sent out on the Ethernet interface.

```
acf-can-bridge -- a program designed to receive CAN messages from a remote CAN
bus over Ethernet using Open1722.
--canif=CAN_IF CAN interface
-c, --count=COUNT Set count of CAN messages per Ethernet frame
-d, --dst-addr=MACADDR Stream destination MAC address (If Ethernet)
--fd Use CAN-FD
-i, --ifname=IFNAME Network interface (If Ethernet)
--listener-stream-id=STREAM_ID
Stream ID for listener stream
-n, --dst-nw-addr=NW_ADDR Stream destination network address and port (If
UDP)
-p, --udp-port=UDP_PORT UDP Port to listen on (if UDP)
--talker-stream-id=STREAM_ID
Stream ID for talker stream
-t, --tscf Use TSCF
-u, --udp Use UDP
-?, --help Give this help list
--usage Give a short usage message
```

## Quickstart Tutorials
### 1. Tunneling CAN over IEEE 1722 using Linux CAN utilities
Here is an example of how CAN frames can be tunneled over an Ethernet link using _acf-can-talker_ and _acf-can-listener_.

```
vcan0 -> acf-can-talker -> Ethernet/UDP -> acf-can-listener -> vcan1
```

We use two virtual CAN interfaces, _vcan0_ and _vcan1_, which can be setup using following commands:
```
$ modprobe vcan
$ ip link add dev vcan0 type vcan # Execute these commands also for vcan1
$ ip link set dev vcan0 up
```

### Generate CAN traffic
#### Generate CAN traffic
On Terminal 1, generate CAN traffic for vcan0:
```
$ cangen vcan0
```

In the following, we tunnel this generated CAN traffic over Ethernet to _vcan1_

### Use Talker Application for tunneling
#### Use Talker Application for tunneling
On Terminal 2, pipe generated CAN traffic from vcan0 to _acf-can-talker_. Here, we use UDP encapsulation.
```
$ ./acf-can-talker -u --dst-nw-addr 127.0.0.1:17220 --canif vcan0
Expand All @@ -71,7 +110,7 @@ Alternatively, we can directly use Ethernet for transport.
$ ./acf-can-talker --dst-addr aa:bb:cc:dd:ee:ff -i eth0 --canif vcan0
```

### Use Listener Application for receiving
#### Use Listener Application for receiving
On Terminal 3, receive the IEEE 1722 traffic using _acf-can-listener_ and put the CAN frame out on vcan1.

If the talker uses UDP encapsulation:
Expand All @@ -84,5 +123,26 @@ Alternatively, if Ethernet is directly used:
$ ./acf-can-listener --dst-addr aa:bb:cc:dd:ee:ff -i eth0 --canif vcan0
```

#### Receive CAN traffic

You can now compare CAN traffic seen on _vcan0 and vcan1_ to check if the tunneling works.
```
candump vcan0 # use another terminal for vcan1
```
Note that the tunneling works in these examples only in one direction (_vcan0_ -> _vcan1_).

### 2. Bridging Ethernet with CAN

```
vcan0 <-> acf-can-bridge <-> Ethernet/UDP
```

- Create virtual CAN _vcan0_ and generate traffic on it as shown above in Tutorial 1.
- Execute the _acf-can-bridge_
```
$ ./acf-can-bridge --dst-addr aa:bb:cc:dd:ee:ff -i eth0 --canif vcan0
```
- Execute wireshark and capture Ethernet packets on _eth0_.
- (Optional) You could also use the _acf-can-talker_ to generate IEEE 1722 ACF frames on _eth0_, which will then be sent as CAN frames on _vcan0_.


4 changes: 2 additions & 2 deletions examples/acf-can/acf-can-listener.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -62,15 +62,15 @@ static char can_ifname[IFNAMSIZ];
static uint64_t listener_stream_id = STREAM_ID;

static char doc[] =
"\nacf-can-listener -- a program designed to receive CAN messages from a remote CAN bus over Ethernet using Open1722.\
"\nacf-can-listener -- a program to receive CAN messages from a remote CAN bus over Ethernet using Open1722.\
\vEXAMPLES\n\
acf-can-listener -i eth0 -d aa:bb:cc:dd:ee:ff --canif can1\n\
\t(tunnel Open1722 CAN messages received from eth0 to can1)\n\
acf-can-listener --canif can1 -u -p 17220\n\
\t(tunnel Open1722 CAN messages received over UDP from port 17220 to can1)";

static struct argp_option options[] = {
{"udp", 'u', 0, 0, "Use UDP" },
{"udp", 'u', 0, 0, "Use UDP (Default: Ethernet)" },
{"fd", ARGPARSE_CAN_FD_OPTION, 0, 0, "Use CAN-FD"},
{"canif", ARGPARSE_CAN_IF_OPTION, "CAN_IF", 0, "CAN interface"},
{"ifname", 'i', "IFNAME", 0, "Network interface (If Ethernet)"},
Expand Down
6 changes: 3 additions & 3 deletions examples/acf-can/acf-can-talker.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -61,16 +61,16 @@ static char can_ifname[IFNAMSIZ];
static uint64_t talker_stream_id = STREAM_ID;

static char doc[] =
"\nacf-can-talker -- a program designed to send CAN messages to a remote CAN bus over Ethernet using Open1722.\
"\nacf-can-talker -- a program to send CAN messages to a remote CAN bus over Ethernet using Open1722.\
\vEXAMPLES\n\
acf-can-talker -i eth0 -d aa:bb:cc:ee:dd:ff --canif vcan0\n\
\t(tunnel transactions from CAN vcan0 over Ethernet eth0)\n\n\
acf-can-talker -u --dst-nw-addr 10.0.0.2:17220 --canif vcan1\n\
\t(tunnel transactions from vcan1 interface using UDP)";

static struct argp_option options[] = {
{"tscf", 't', 0, 0, "Use TSCF"},
{"udp", 'u', 0, 0, "Use UDP" },
{"tscf", 't', 0, 0, "Use TSCF (Default: NTSCF)"},
{"udp", 'u', 0, 0, "Use UDP (Default: Ethernet)" },
{"fd", ARGPARSE_CAN_FD_OPTION, 0, 0, "Use CAN-FD"},
{"count", 'c', "COUNT", 0, "Set count of CAN messages per Ethernet frame"},
{"canif", ARGPARSE_CAN_IF_OPTION, "CAN_IF", 0, "CAN interface"},
Expand Down

0 comments on commit c0cf41d

Please sign in to comment.