exbee

v0.0.5

exbee v0.0.5 Exbee View Source

Communicate with XBee wireless radios in Elixir.

This assumes that XBee modules are in API mode. In API mode, XBee modules send and receive commands via encoded frames. Possible frames include:

Frames are sent via the Exbee.send_frame/2 function. Frames received on the serial port are reported as messages to the current process. The messages have the following form:

{:exbee, frame}

This example starts an Exbee process and sends an Exbee.ATCommandFrame to change the value of the NJ parameter. Upon receiving the command, the XBee module will return an Exbee.ATCommandStatusFrame indicating the status of the request.

iex> {:ok, pid} = Exbee.start_link(serial_port: "COM1")
iex> Exbee.send_frame(pid, %Exbee.ATCommandFrame{command: "NJ", value: 1})
:ok

iex> flush()
{:exbee, %Exbee.ATCommandResultFrame{command: "NJ", status: :ok, value: <0x01>}}

Link to this section Summary

Types

device_option()

Functions

init(list)

Invoked when the server is started. start_link/3 or start/3 will block until it returns

send_frame(pid, frame)

Send a frame to a given device

serial_ports()

Return a map of available serial devices with information about each

start_link(options \\ [])

Start a new Exbee process

stop(pid)

Shuts down the device process

Link to this section Types

Link to this type device_option() View Source 
device_option() ::
  {:serial_port, String.t()}
  | {:speed, non_neg_integer()}
  | {:data_bits, 5..8}
  | {:stop_bits, 1..2}
  | {:parity, :none | :even | :odd | :space | :mark}
  | {:flow_control, :none | :hardware | :software}

Link to this section Functions

Link to this function init(list) View Source

Invoked when the server is started. start_link/3 or start/3 will block until it returns.

args is the argument term (second argument) passed to start_link/3.

Returning {:ok, state} will cause start_link/3 to return {:ok, pid} and the process to enter its loop.

Returning {:ok, state, timeout} is similar to {:ok, state} except handle_info(:timeout, state) will be called after timeout milliseconds if no messages are received within the timeout.

Returning {:ok, state, :hibernate} is similar to {:ok, state} except the process is hibernated before entering the loop. See c:handle_call/3 for more information on hibernation.

Returning :ignore will cause start_link/3 to return :ignore and the process will exit normally without entering the loop or calling c:terminate/2. If used when part of a supervision tree the parent supervisor will not fail to start nor immediately try to restart the GenServer. The remainder of the supervision tree will be (re)started and so the GenServer should not be required by other processes. It can be started later with Supervisor.restart_child/2 as the child specification is saved in the parent supervisor. The main use cases for this are:

  • The GenServer is disabled by configuration but might be enabled later.
  • An error occurred and it will be handled by a different mechanism than the Supervisor. Likely this approach involves calling Supervisor.restart_child/2 after a delay to attempt a restart.

Returning {:stop, reason} will cause start_link/3 to return {:error, reason} and the process to exit with reason reason without entering the loop or calling c:terminate/2.

Callback implementation for GenServer.init/1.

Link to this function send_frame(pid, frame) View Source 
send_frame(pid(), Exbee.EncodableFrame.t()) :: :ok | {:error, term()}

Send a frame to a given device.

A frame must implement the Exbee.EncodableFrame protocol, making it possible to define custom frames.

Link to this function serial_ports() View Source 
serial_ports() :: map()

Return a map of available serial devices with information about each.

iex> Exbee.serial_ports()
%{
  "COM1" => %{description: "USB Serial", manufacturer: "FTDI", product_id: 1, vendor_id: 2},
  "COM2" => %{...},
  "COM3" => %{...}
}

Depending on the device and the operating system, not all fields may be returned.

fields are:

  • :vendor_id - The 16-bit USB vendor ID of the device providing the port. Vendor ID to name lists are managed through usb.org
  • :product_id - The 16-bit vendor supplied product ID
  • :manufacturer - The manufacturer of the port
  • :description - A description or product name
  • :serial_number - The device’s serial number if it has one
Link to this function start_link(options \\ []) View Source 
start_link([device_option()]) :: {:ok, pid()} | {:error, term()}

Start a new Exbee process.

iex> {:ok, pid} = Exbee.start_link(serial_port: "COM1", speed: 9600)

Options can either be passed directly, or they’ll be read from :exbee config values. The following options are available:

  • :serial_port - The serial interface connected to the Xbee device.
  • :speed - (number) set the initial baudrate (e.g., 115200)
  • :data_bits - (5, 6, 7, 8) set the number of data bits (usually 8)
  • :stop_bits - (1, 2) set the number of stop bits (usually 1)

  • :parity - (:none, :even, :odd, :space, or :mark) set the parity. Usually this is :none. Other values:

    • :space means that the parity bit is always 0
    • :mark means that the parity bit is always 1
  • :flow_control - (:none, :hardware, or :software) set the flow control strategy.

The following are some reasons for which the device may fail to start:

  • :enoent - the specified port couldn’t be found
  • :eagain - the port is already open
  • :eacces - permission was denied when opening the port
Link to this function stop(pid) View Source 
stop(pid()) :: :ok

Shuts down the device process.