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
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
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
Close the serial port. The GenServer continues to run so that a port can be opened again.
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.
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:
: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
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.
open(GenServer.server(), binary(), [uart_option()]) :: :ok | {:error, term()}
Open a serial port.
The following options are available:
:active
- (true
orfalse
) specifies whether data is received as messages or by callingread/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. Themodule
must implement theNerves.UART.Framing
behaviour. SeeNerves.UART.Framing.None
,Nerves.UART.Framing.Line
, andNerves.UART.Framing.FourByte
. The default isNerves.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
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
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.
set_break(GenServer.server(), boolean()) :: :ok | {:error, term()}
Start or stop sending a break signal.
set_dtr(GenServer.server(), boolean()) :: :ok | {:error, term()}
Set or clear the Data Terminal Ready signal.
set_rts(GenServer.server(), boolean()) :: :ok | {:error, term()}
Set or clear the Request To Send signal.
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
Start up a UART GenServer.
Stop the UART GenServer.
write(GenServer.server(), binary() | [byte()]) :: :ok | {:error, term()}
Write data to the opened UART with the default timeout.
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