cangaroo

cangaroo - Gleam bindings for SocketCAN communication on Linux.

This module provides the public API for interacting with CAN bus interfaces through the Excansock Elixir library. It manages CAN socket connections using OTP actors.

cangaroo attempts to provide a simple, idiomatic Gleam API. Each CAN client runs as an OTP actor that automatically receives incoming CAN frames and forwards them to your application via a process subject.

Values

close

</>

pub fn close(client: types.CanClient) -> Nil

Closes the CAN client and releases all associated resources.

This function sends a shutdown message to the CAN client actor, which will close the underlying CAN socket, stop the GenServer and stop the actor process. After calling this function, the client should no longer be used.

This operation is asynchronous, the function returns immediately after sending the shutdown message. The actual cleanup happens in the background.

recv_own_messages

</>

pub fn recv_own_messages(
  client: types.CanClient,
  value: Bool,
) -> Result(Nil, errors.CanError)

Controls whether this client receives its own transmitted CAN frames.

When enabled, frames sent by this client will also be received back through the messages subject. This can be useful for confirming successful transmission or for debugging purposes.

By default, receiving own messages is disabled.

Note: This setting only has an effect when loopback is also enabled (see set_loopback).

Parameters

client: The CAN client to configure
value: True to receive own messages, False to filter them out

send

</>

pub fn send(
  client: types.CanClient,
  frame: types.CanFrame,
) -> Result(Nil, errors.CanError)

Sends a CAN frame over the bus.

The frame must be a CanFrame containing:

id: The CAN identifier (11-bit standard or 29-bit extended)
data: The payload as a BitArray (up to 8 bytes for standard CAN)

Returns Ok(Nil) if the frame was successfully queued for transmission, or an error if the send operation failed.

set_error_filter

</>

pub fn set_error_filter(
  client: types.CanClient,
  filter: Int,
) -> Result(Nil, errors.CanError)

Sets the error filter mask for receiving CAN error frames.

CAN error frames are special frames generated by the CAN controller to report bus errors, such as bit errors, CRC errors, or bus-off conditions. The error filter is a bitmask that determines which types of errors should be reported to this client.

Parameters

client: The CAN client to configure
filter: A bitmask specifying which error types to receive

set_filters

</>

pub fn set_filters(
  client: types.CanClient,
  filters: List(types.CanFilter),
) -> Result(Nil, errors.CanError)

Sets CAN ID filters to selectively receive only matching frames.

Filters allow you to specify which CAN frames should be received based on their CAN ID. Each filter consists of an id and a mask:

Multiple filters can be specified - a frame is accepted if it matches ANY of the filters (OR logic).

Calling this function replaces any previously set filters.

Parameters

client: The CAN client to configure
filters: A list of CanFilter values defining the acceptance criteria

set_loopback

</>

pub fn set_loopback(
  client: types.CanClient,
  value: Bool,
) -> Result(Nil, errors.CanError)

Enables or disables local loopback of transmitted CAN frames.

When loopback is enabled, frames sent by this socket are also delivered to other CAN sockets on the same interface (but not to this socket itself, unless recv_own_messages is also enabled).

By default, loopback is typically enabled on CAN interfaces.

Parameters

client: The CAN client to configure
value: True to enable loopback, False to disable it

start_link

</>

pub fn start_link(
  interface: String,
) -> Result(types.CanClient, errors.CanError)

Creates a new CAN client and connects it to the specified network interface.

This function starts an OTP actor that manages the CAN socket connection. The actor automatically receives incoming CAN frames from the bus and forwards them to a subject that you can access via types.messages(client).

The interface parameter should be the name of a CAN network interface on your Linux system, such as "can0" for a physical CAN adapter or "vcan0" for a virtual CAN interface used in testing.

Returns Ok(CanClient) on success, or an error if the connection fails.