Nerves.UART v1.1.1 Nerves.UART View Source

Find and use UARTs, serial ports, and more.

Link to this section Summary

Functions

Close the serial port. The GenServer continues to run so that a port can be opened again

Change the serial port configuration after open/3 has been called. See open/3 for the valid options

Waits until all data has been transmitted. See tcdrain(3) for low level details on Linux or OSX. This is not implemented on Windows

Return a map of available ports with information about each one. The map looks like this:

   %{ "ttyS0" -> %{vendor_id: 1234, product_id: 1,
                   manufacturer: "Acme Corporation", serial_number: "000001"},
      "ttyUSB0" -> ${vendor_id: 1234, product_id: 2} }

Depending on the port and the operating system, not all fields may be returned. Informational fields are

Flushes the :receive buffer, the :transmit buffer, or :both

Open a serial port

Read data from the UART. This call returns data as soon as it’s available or after timing out

Send a continuous stream of zero bits for a duration in milliseconds. By default, the zero bits are transmitted at least 0.25 seconds

Start or stop sending a break signal

Set or clear the Data Terminal Ready signal

Set or clear the Request To Send signal

Returns a map of signal names and their current state (true or false). Signals include

Start up a UART GenServer

Stop the UART GenServer

Write data to the opened UART with the default timeout

Write data to the opened UART. It’s possible for the write to return before all of the data is actually transmitted. To wait for the data, call drain/1

Link to this section Types

Link to this type uart_option() View Source
uart_option() ::
  {:active, boolean()} |
  {:speed, non_neg_integer()} |
  {:data_bits, 5..8} |
  {:stop_bits, 1..2} |
  {:parity, :none | :even | :odd | :space | :mark} |
  {:flow_control, :none | :hardware | :software} |
  {:framing, module() | {module(), [term()]}} |
  {:rx_framing_timeout, integer()}

Link to this section Functions

Link to this function close(pid) View Source
close(GenServer.server()) :: :ok | {:error, term()}

Close the serial port. The GenServer continues to run so that a port can be opened again.

Link to this function configure(pid, opts) View Source
configure(GenServer.server(), [uart_option()]) ::
  :ok |
  {:error, term()}

Change the serial port configuration after open/3 has been called. See open/3 for the valid options.

Link to this function drain(pid) View Source
drain(GenServer.server()) :: :ok | {:error, term()}

Waits until all data has been transmitted. See tcdrain(3) for low level details on Linux or OSX. This is not implemented on Windows.

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

Return a map of available ports with information about each one. The map looks like this:

   %{ "ttyS0" -> %{vendor_id: 1234, product_id: 1,
                   manufacturer: "Acme Corporation", serial_number: "000001"},
      "ttyUSB0" -> ${vendor_id: 1234, product_id: 2} }

Depending on the port and the operating system, not all fields may be returned. Informational 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 flush(pid, direction \\ :both) View Source

Flushes the :receive buffer, the :transmit buffer, or :both.

See tcflush(3) for low level details on Linux or OSX. This calls PurgeComm on Windows.

Link to this function open(pid, name, opts \\ []) View Source
open(GenServer.server(), binary(), [uart_option()]) ::
  :ok |
  {:error, term()}

Open a serial port.

The following options are available:

  • :active - (true or false) specifies whether data is received as messages or by calling read/2. See discussion below.

  • :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.

  • :framing - (module or {module, args}) set the framing for data. The module must implement the Nerves.UART.Framing behaviour. See Nerves.UART.Framing.None, Nerves.UART.Framing.Line, and Nerves.UART.Framing.FourByte. The default is Nerves.UART.Framing.None.

  • :rx_framing_timeout - (milliseconds) this specifies how long incomplete frames will wait for the remainder to be received. Timed out partial frames are reported as {:partial, data}. A timeout of <= 0 means to wait forever.

Active mode defaults to true and means that data received on the UART is reported in messages. The messages have the following form:

{:nerves_uart, serial_port_name, data}

or

{:nerves_uart, serial_port_name, {:error, reason}}

When in active mode, flow control can not be used to push back on the sender and messages will accumulated in the mailbox should data arrive fast enough. If this is an issue, set :active to false and call read/2 manually when ready for more data.

On success, open/3 returns :ok. On error, {:error, reason} is returned. The following are some reasons:

  • :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 read(pid, timeout \\ 5000) View Source
read(GenServer.server(), integer()) ::
  {:ok, binary()} |
  {:error, term()}

Read data from the UART. This call returns data as soon as it’s available or after timing out.

Returns {:ok, binary}, where binary is a binary data object that contains the read data, or {:error, reason} if an error occurs.

Typical error reasons:

  • :ebadf - the UART is closed
  • :einval - the UART is in active mode
Link to this function send_break(pid, duration \\ 250) View Source
send_break(GenServer.server(), integer()) :: :ok | {:error, term()}

Send a continuous stream of zero bits for a duration in milliseconds. By default, the zero bits are transmitted at least 0.25 seconds.

This is a convenience function for calling set_break/2 to enable the break signal, wait, and then turn it off.

Link to this function set_break(pid, value) View Source
set_break(GenServer.server(), boolean()) :: :ok | {:error, term()}

Start or stop sending a break signal.

Link to this function set_dtr(pid, value) View Source
set_dtr(GenServer.server(), boolean()) :: :ok | {:error, term()}

Set or clear the Data Terminal Ready signal.

Link to this function set_rts(pid, value) View Source
set_rts(GenServer.server(), boolean()) :: :ok | {:error, term()}

Set or clear the Request To Send signal.

Link to this function signals(pid) View Source
signals(GenServer.server()) :: map() | {:error, term()}

Returns a map of signal names and their current state (true or false). Signals include:

  • :dsr - Data Set Ready
  • :dtr - Data Terminal Ready
  • :rts - Request To Send
  • :st - Secondary Transmitted Data
  • :sr - Secondary Received Data
  • :cts - Clear To Send
  • :cd - Data Carrier Detect
  • :rng - Ring Indicator
Link to this function start_link(opts \\ []) View Source
start_link([term()]) :: {:ok, pid()} | {:error, term()}

Start up a UART GenServer.

Stop the UART GenServer.

Link to this function write(pid, data) View Source
write(GenServer.server(), binary() | [byte()]) ::
  :ok |
  {:error, term()}

Write data to the opened UART with the default timeout.

Link to this function write(pid, data, timeout) View Source
write(GenServer.server(), binary() | [byte()], integer()) ::
  :ok |
  {:error, term()}

Write data to the opened UART. It’s possible for the write to return before all of the data is actually transmitted. To wait for the data, call drain/1.

This call blocks until all of the data to be written is in the operating system’s internal buffers. If you’re sending a lot of data on a slow link, supply a longer timeout to avoid timing out prematurely.

Returns :ok on success or {:error, reason} if an error occurs.

Typical error reasons:

  • :ebadf - the UART is closed