@csllc/cs-mb-socketcand NPM

cs-mb-socketcand

This package implements a TCP/IP client that detects and connects to a socketcand server (see https://github.com/linux-can/socketcand), allowing access to a CAN Bus network over an Ethernet network.

The main features of this package are:

socketcand server detection by listening for UDP beacon broadcasts
Ability to connect to a socketcand server, and send and receive CAN messages
Support for CAN message filtering, as allowed by socketcand
Extension of the NodeJS EventEmitter class, allowing bus and message events to be emitted

The package exports a class definition that is compatible with cs-modbus and other CAN modules such as can-usb-com and cs-pcan-usb. This allows cs-modbus to communicate with motor controllers via a socketcand server.

This package can be imported as follows:

const Factory = require('@csllc/cs-mb-socketcand');
let scanner = new Factory();

:warning: This package's interface underwent a rewrite in version 3.0.0, and all J1939 code was removed. Any code using version 2.x of this package may not be compatible with version 3.0.0 or newer.

Module overview

Connection management methods

.connect()
.disconnect()

Message transmission methods

.send()
.write()
.add()
.update()
.delete()

Message reception methods

.subscribe()
.unsubscribe()
.filter()

Bus management methods

.rawMode()
.bcmMode()
.isotpMode()
.statistics()
.echo()

`can-usb-com`-compatible methods

.list()
.open()
.close()
.isOpen()
.status()

Emitted events

scanStart
scanStop
discover
connect
disconnect
error
write
data

Detecting socketcand servers

The .startScanning() method causes the module to start listening for socketcand instances on the network. When an announcement is received, a discover event is emitted. This event is emitted each time an announcement is received. The package will continue discovering the network(s) as long as scanning is enabled.

Calling .startScanning() has the side effect of closing any active TCP connections before the scan begins.

The .stopScanning() method ends the scan; no further discover events are emitted after this method is called.

Alternatively, the .list() method scans the network for a predefined amount of time (5 seconds by default) and returns a list of found server.

Connection management

The connect method is used to establish a TCP connection to the server. This method returns a promise that resolves when the connection is established. An open event is also emitted when the connection succeeds. This connection can be either passive (listening only) or active (send and receive messages).

The disconnect method is used to close an open TCP connection.

Message transmission

The following methods allow sending messages on the CANBUS:

.send(): Sends a single CANBUS message using a complete ID (e.g. 29 bits) and data payload of up to 8 bytes. This method returns synchronously after the message is initiated. There is no facility to confirm receipt of the message. Example: send( 0x123, [] )
.write(): Accepts a packet in the style used by the can-usb-com package. This method allows software to use cs-mb-socketcand in place of a USB CAN dongle. Example: See examples/test.js
.add(): Schedules a message to be sent periodically. Example, send the CAN frame 123#1122334455667788 every 10 microseconds: add( 1, 0, 0x123, [0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88])
.update(): Updates a scheduled message transmission (that was added using add) to change its contents or rate. The transmission timers are not touched. Example: update( 0x123, [ 0x11, 0x22, 0x33] )
.delete(): Removes a scheduled message transmission. Example: delete( 0x123 )

Message reception

Message reception is via events emitted by the class instance. When messages arrive that match the configured filters, they are emitted as a data event.

.subscribe(): Add a subscription to a specific CAN ID. An interval in seconds or microseconds may be set to throttle the number of frames sent. Example: subscribe( 0, 0, 0x123 )
.unsubscribe(): Unsubscribe from a message that was subscribed or filtered. This deletes all subscriptions or filters for a specific CAN ID.
.filter(): Configure the broadcast manager for reception of frames with a given CAN ID. Frames are only sent when they match the pattern that is provided. Examples:
- Receive CAN ID 0x123 and check for changes in the first byte: filter( 0, 0, 0x123, [0xFF])
- Receive CAN ID 0x123 and check for changes in given mask: filter( 0, 0, 0x123, [0xFF, 0x00, 0xF8, 0x00, 0x00, 0x00, 0x00, 0x00])
- As above but throttle receive update rate down to 1.5 seconds: filter( 1, 500000, 0x123, [0xFF, 0x00, 0xF8, 0x00, 0x00, 0x00, 0x00, 0x00])

Raw vs BCM mode filter behavior

The connection between the client and server is initially opened in RAW mode, in which no filter is applied and all CAN messages are send to the client.

If filters are specified in the constructor's filters option, or the filter() method is called, the connection will be switched to BCM mode to enable filtering.

Bus management

.rawMode(): Switch to raw mode
.statistics(): Enable transmission of bus statistics, at a specified interval. This is only supported when the bus is operating in raw mode. To disable statistics, call this method specifying an interval of 0. Example: statistics(500).
.bcmMode(): Switch to broadcast manager (BCM) mode
.isotpMode(): Switch to ISO TP mode

`can-usb-com`-compatible methods

These methods return Promises, which are resolved or rejected when a request is complete.

.list(): Scan for a predetermined amount of time, and resolve with an array of discovered socketcand servers. One of the array elements can then be passed to .open.
.open(): Alias of .connect()
.close(): Alias of .disconnect()
.isOpen(): Returns true if the TCP socket is connected, false otherwise
.status(): Resolves with the full status of the instance

Constructor options

Just like can-usb-com and other CS CAN modules, this module can accept options passed to its constructor when it is instantiated.

Refer to examples/test.js for a working example that uses this feature.

Development

Before updating or modifying this package, please

Lint any changes using eslint.
Verify that example code works

Do not run any tests on a bus with active traffic, since receiving unexpected CAN packets may confuse the tests.

Examples

Refer to the examples folder for complete, functioning examples. In order to run the examples, you will need a functioning socketcand server on your network.