# CANBus : CAN-Bus device

This module provides various CAN-Bus operations, supports BASIC and PELI modes, and supports CAN and CAN FD packet types.

This module is designed in a synchronous mode. It is convenient to port the CAN-Bus protocol of other languages to the JSRE environment. Of course, the user can also use the iosched event to encapsulate the module into asynchronous mode with EventEmitter.

User can use the following code to import the CAN-Bus module.

var Canbus = require('canbus');

# Example

• Synchronize

var Canbus = require('canbus');

// Open CAN-Bus device.
var canbus = Canbus.open(0);

// Initial.
canbus.setMode('peli');
canbus.start();

// Create a CAN Frame buffer.
var frame = Canbus.canFrame();

// Echo all recevied frame.
while (true) {
  var result = canbus.read(frame);
  if (result > 0) {
    console.log('CAN-Bus recv:', frame);
    canbus.write(frame);

  } else if (result < 0) {
    console.log('CAN-Bus state:', canbus.state);
    canbus.reset();
    canbus.start();
  }
}

• Asynchronize

var Canbus = require('canbus');
var iosched = require('iosched');

// Open CAN-Bus device.
var canbus = Canbus.open(0);

// Initial.
canbus.setMode('peli');
canbus.start();

// Create a CAN Frame buffer.
var frame = Canbus.canFrame();

// Use IoEvent.
var ioevent = iosched.event(iosched.READ, canbus.fd(), 
() => {
  var result = canbus.read(frame);
  if (result > 0) {
    console.log('CAN-Bus recv:', frame);
    canbus.write(frame);

  } else if (result < 0) {
    console.log('CAN-Bus state:', canbus.state);
    canbus.reset();
    canbus.start();
  }
  return true;
});

iosched.add(ioevent);

while (true) {
  iosched.poll(); // Event poll.
}

# Support

The following shows Canbus module APIs available for each permissions.

# Canbus Class

# new Canbus(devNo)

• devNo {Integer} CAN-Bus device number in system.
• Returns: {Object} CAN-Bus device object.

Open a CAN-Bus device with the specified device number.

# Example

// Open /dev/can0 canbus device.
var canbus = new Canbus(0);

# Canbus.open(devNo)

• devNo {Integer} CAN-Bus device number in system.
• Returns: {Object} CAN-Bus device object.

Open a CAN-Bus device with the specified device number.

Same as new Canbus(), but does not throw an exception, returning undefined means opening failed.

# Example

// Open /dev/can1 canbus device.
var canbus = Canbus.open(1);

# Canbus.canFrame([num])

• num {Integer} CAN packet frame number. default: 1.
• Returns: {Object} | {Array} If num is 1 this function return a CAN packet frame object, if num bigger than 1, this function return a CAN packet frame array.

The frame object has the following items:

• id {Integer} CAN packet ID.
• channel {Integer} CAN controller channel.
• isExt {Boolean} Is this a extension packet.
• isRemote {Boolean} Is this a remote packet.
• length {Integer} Data bytes in this packet.
• buffer {Buffer} Data buffer in this packet, length is 8 defined by constant: Canbus.CAN_MAX_DATA.

# Example

// Create a CAN packet frame.
var frame = Canbus.canFrame();

// Create a CAN packet frame array with length 10.
var frameArray = Canbus.canFrame(10);

# Canbus.canFdFrame([num])

• num {Integer} CAN FD packet frame number. default: 1.
• Returns: {Object} | {Array} If num is 1 this function return a CAN FD packet frame object, if num bigger than 1, this function return a CAN FD packet frame array.

The frame object has the following items:

• id {Integer} CAN packet ID.
• channel {Integer} CAN controller channel.
• isExt {Boolean} Is this a extension packet.
• isRemote {Boolean} Is this a remote packet.
• flags {Integer} CAN FD packet flags, This is a 'Bit or' integer, include: Canbus.CAN_FD_FLAG_EDL, Canbus.CAN_FD_FLAG_BRS, Canbus.CAN_FD_FLAG_ESI bit.
• length {Integer} Data bytes in this packet.
• buffer {Buffer} Data buffer in this packet, length is 64 defined by constant: Canbus.CAN_FD_MAX_DATA.

# Example

// Create a CAN FD packet frame.
var frame = Canbus.canFdFrame();

// Create a CAN FD packet frame array with length 10.
var frameArray = Canbus.canFdFrame(10);

# Canbus Object

# canbus.fd()

• Returns: {Integer} Canbus object file descriptor.

Get current canbus object event file descriptor. Only for iosched readable and writable event detection in current tasks.

# canbus.state

• {Integer}

The current state of CAN-Bus. If the bus state is normal, it returns 0. Other values indicate a bus error. This error is ‘Bit OR’ integer.

# Example

var state = canbus.state;

if (state & Canbus.CAN_DEV_BUS_OVERRUN) {
  console.error('CAN controller receive buffer overrun.');
}
if (state & Canbus.CAN_DEV_BUS_OFF) {
  console.error('CAN bus is off.');
}
if (state & Canbus.CAN_DEV_BUS_LIMIT) {
  console.error('CAN bus report limits errors.');
}
if (state & Canbus.CAN_DEV_BUS_PASSIVE) {
  console.error('CAN bus reports passive error.');
}
if (state & Canbus.CAN_DEV_BUS_RXBUFF_OVERRUN) {
  console.error('CAN driver buffer overrun.');
}
if (state & Canbus.CAN_DEV_BUS_RXBUFF_OVERRUN) {
  console.error('CAN driver buffer overrun.');
}

if (canbus.state & Canbus.CAN_DEV_BUS_OVERRUN) {
  ...;
}
if (canbus.state & Canbus.CAN_DEV_BUS_OFF) {
  ...;
}

# canbus.close()

Close this canbus and reclaiming file descriptors. If user forgets to call this function, the file descriptor is automatically reclaimed when the object is destroyed.

# Example

canbus.close();

# canbus.start()

• Returns: {Boolean} Whether the CAN-Bus device starts successfully. If successfully return: true, otherwise return: false. You can use console.log(sys.error(sys.errno)) to display the error message.

Start the CAN-Bus device, user must start the device before sending and receiving data packets.

# Example

canbus.start();

# canbus.read(frame[, timeout])

• frame {Object} Save the received packet to this object.
• timeout {Integer} Read timeout in milliseconds. default: undefined means wait forever.
• Returns: Number of read packet frames. When the return value is 0, it means timeout. If it is negative, CAN-Bus has an error. You can use canbus.state to get the bus error condition.

Read one CAN packet from CAN-Bus and stored in the frame object. If CAN-Bus is CAN FD mode, frame must be created using Canbus.canFdFrame(), if in standard CAN mode, frame is created using Canbus.canFrame().

# Example

var frame = Canbus.canFrame();

var num = canbus.read(frame);

# canbus.read(frameArray[, timeout])

• frameArray {Array} Save the received packet to this frame object array.
• timeout {Integer} Read timeout in milliseconds. default: undefined means wait forever.
• Returns: Number of read packet frames. When the return value is 0, it means timeout. If it is negative, CAN-Bus has an error. You can use canbus.state to get the bus error condition.

Receive multiple packets from CAN-Bus and stored in the frameArray frame object. If CAN-Bus is CAN FD mode, frameArray must be created using Canbus.canFdFrame(num), if in standard CAN mode, frameArray is created using Canbus.canFrame(num).

# Example

// argument must bigger than 1.
var frameArray = Canbus.canFrame(10);

var num = canbus.read(frameArray);

# canbus.write(frame[, timeout])

• frame {Object} The packet to be send.
• timeout {Integer} Write timeout in milliseconds. default: undefined means wait forever.
• Returns: Number of read packet frames. When the return value is 0, it means timeout. If it is negative, CAN-Bus has an error. You can use canbus.state to get the bus error condition.

Send one CAN packet to CAN-Bus. If CAN-Bus is CAN FD mode, frame must be created using Canbus.canFdFrame(), if in standard CAN mode, frame is created using Canbus.canFrame().

# Example

var frame = Canbus.canFrame();

frame.id = 1;
frame.channel = 0;
frame.isExt = false;
frame.isRemote = false;
frame.length = 1;
frame.buffer[0] = 0x01;

var num = canbus.write(frame);

# canbus.write(frameArray[, count[, timeout]])

• frameArray {Array} The packet array to be send.
• count {Integer} The maximum number of packets we want to be send. default: frameArray.length.
• timeout {Integer} Write timeout in milliseconds. default: undefined means wait forever.
• Returns: Number of read packet frames. When the return value is 0, it means timeout. If it is negative, CAN-Bus has an error. You can use canbus.state to get the bus error condition.

Send multiple CAN packet to CAN-Bus. If CAN-Bus is CAN FD mode, frameArray must be created using Canbus.canFdFrame(num), if in standard CAN mode, frameArray is created using Canbus.canFrame(num).

# Example

// argument must bigger than 1.
var frameArray = Canbus.canFrame(2);

frameArray[0].id = 1;
frameArray[0].channel = 0;
frameArray[0].isExt = false;
frameArray[0].isRemote = false;
frameArray[0].length = 1;
frameArray[0].buffer[0] = 0x01;

frameArray[1].id = 2;
frameArray[1].channel = 0;
frameArray[1].isExt = false;
frameArray[1].isRemote = false;
frameArray[1].length = 1;
frameArray[1].buffer[0] = 0x02;

var num = canbus.write(frameArray, 2);

# canbus.reset()

Reset the CAN-Bus controller. If detects a bus error, you can use this function to reset the controller and then call canbus.start() to start the bus for packet transmission and reception.

# Example

if (canbus.state) {
  // Reset and restart canbus.
  canbus.reset();
  canbus.start();
}

# canbus.flush([option])

• option {String} If 'r' means clear the receive buffer, if 'w' means clear the send buffer. default: undefined means clear receive and send buffer.

If the you need to discard the current CAN driver send or receive queued data, you can use this function to clear.

# Example

canbus.flush();

# canbus.drain()

If there has packet in the current send queue that has not been sent, the function returns after waiting for all packets in the send queue to be sent.

# Example

canbus.drain();

# canbus.count()

• Returns: {Integer} Returns how many packets in receive queue.

If there are unread packets in the receive buffer, this function returns the number of packets, otherwise it returns 0.

# Example

var cnt = canbus.count();

# canbus.setBaudrate(baudRate)

• baudRate {Integer} CAN-Bus baud rate, the following baud rates are recommended: 1000000(1Mpbs) ~ 5000(5Kbps).
• Returns: {Boolean} Returns true if the setting is successful, false otherwise. If the frequency divider cannot configure CAN-Bus to the specified baud rate, it returns false.

Set CAN-Bus baud rate.

# Example

// Set to 100Kbps.
canbus.setBaudrate(100000);

# canbus.setMode(mode)

• mode {String} CAN-Bus mode, Only allowed to be set to 'basic' or 'peli'.
• Returns: {Boolean} Returns true if the setting is successful, false otherwise.

Set CAN-Bus mode BASIC or PELI.

# Example

// Set to PELI CAN.
canbus.setMode('peli');

# canbus.setCanFd(enable)

• enable {Boolean} Whether to use CAN FD long package mode.
• Returns: {Boolean} Returns true if the setting is successful, false otherwise.

Set CAN-Bus packet type STANDARD or CAN FD.

# Example

// Set to STANDARD CAN.
canbus.setCanFd(false);

# canbus.setSilent(enable)

• enable {Boolean} Set CAN controller to silent mode or not.
• Returns: {Boolean} Returns true if the setting is successful, false otherwise.

Set CAN controller to silent mode or not, and if in silent mode, only allows reception.

# Example

// Set CAN controller to silent mode.
canbus.setSilent(true);