# `Circuits.UART`
[🔗](https://github.com/elixir-circuits/circuits_uart/blob/v1.5.5/lib/circuits_uart.ex#L16)

Find and use UARTs, serial ports, and more.

# `uart_option`

```elixir
@type uart_option() ::
  {:active, boolean()}
  | {:speed, non_neg_integer()}
  | {:data_bits, 5..8}
  | {:stop_bits, 1..2}
  | {:parity, :none | :even | :odd | :space | :mark | :ignore}
  | {:flow_control, :none | :hardware | :software}
  | {:framing, module() | {module(), [term()]}}
  | {:rx_framing_timeout, integer()}
  | {:id, :name | :pid}
  | {:rs485_enabled, boolean()}
  | {:rs485_rts_on_send, boolean()}
  | {:rs485_rts_after_send, boolean()}
  | {:rs485_rx_during_tx, boolean()}
  | {:rs485_terminate_bus, boolean()}
  | {:rs485_delay_rts_before_send, pos_integer()}
  | {:rs485_delay_rts_after_send, pos_integer()}
```

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `close`

```elixir
@spec close(GenServer.server()) :: :ok | {:error, File.posix()}
```

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

# `configuration`

```elixir
@spec configuration(GenServer.server()) :: {binary() | :closed, [uart_option()]}
```

Get the configuration of the serial port.

# `configure`

```elixir
@spec configure(GenServer.server(), [uart_option()]) :: :ok | {:error, File.posix()}
```

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

# `controlling_process`

```elixir
@spec controlling_process(GenServer.server(), pid()) :: :ok | {:error, File.posix()}
```

Change the controlling process that
receives events from an active uart.

# `drain`

```elixir
@spec drain(GenServer.server()) :: :ok | {:error, File.posix()}
```

Waits until all data has been transmitted. See
[tcdrain(3)](http://linux.die.net/man/3/tcdrain) for low level details on
Linux or OSX. This is not implemented on Windows.

# `enumerate`

```elixir
@spec enumerate() :: map()
```

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

```elixir
 %{"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

# `find_pids`

```elixir
@spec find_pids() :: [{binary() | :closed, pid()}]
```

Find UARTs.

This is intended as a diagnostic function for finding UARTs that you may have
opened and forgotten about. Since a UART can only be opened once, this helps
you find the problematic one so that you can close it.

It returns a list of {pid, uart_name} tuples.

NOTE: Do not rely on this function in production code. It may change if
updates to the interface make it more convenient to use.

# `flush`

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

See [tcflush(3)](http://linux.die.net/man/3/tcflush) for low level details on
Linux or OSX. This calls `PurgeComm` on Windows.

# `init`

# `open`

```elixir
@spec open(GenServer.server(), binary(), [uart_option()]) ::
  :ok | {:error, File.posix()}
```

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
  * `:ignore` means that the parity bit is ignored (Linux/OSX only)

* `: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 `Circuits.UART.Framing` behaviour. See
  `Circuits.UART.Framing.None`, `Circuits.UART.Framing.Line`, and
  `Circuits.UART.Framing.FourByte`. The default is `Circuits.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.

* `:id` - (`:name` or `:pid`) specify what to return with the uart active
  messages. with `:name` the messages are returned as `{:circuits_uart,
  serial_port_name, data}` otherwise they are returned as `{:circuits_uart,
  pid, data}`. The name and pid are the name of the connected UART or the pid
  of the Circuits.UART server pid as returned by `start_link/1`. The default
  value is `:name`.

The following options are supported on Linux only:

* `:rs485_enabled` - (`true` or `false`) enable RS485 mode.
* `:rs485_rts_on_send` - (`true` or `false`) enable RTS on send.
* `:rs485_rts_after_send` - (`true` or `false`) enable RTS after send.
* `:rs485_rx_during_tx` - (`true` or `false`) enable RX during TX (loopback).
* `:rs485_terminate_bus` - (`true` or `false`) enable bus termination.
* `:rs485_delay_rts_before_send` - (milliseconds) delay RTS before send.
* `:rs485_delay_rts_after_send` - (milliseconds) delay RTS after send.

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

```elixir
{:circuits_uart, serial_port_id, data}
```

or

```elixir
{:circuits_uart, serial_port_id, {: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`

```elixir
@spec read(GenServer.server(), non_neg_integer()) ::
  {:ok, binary()} | {:ok, {:partial, binary()}} | {:error, File.posix()}
```

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, `{:error, reason}` if an error occurs, or `{:ok, <<>>}` after timing out.

Typical error reasons:

* `:ebadf` - the UART is closed
* `:einval` - the UART is in active mode

# `send_break`

```elixir
@spec send_break(GenServer.server(), integer()) :: :ok | {:error, File.posix()}
```

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`

```elixir
@spec set_break(GenServer.server(), boolean()) :: :ok | {:error, File.posix()}
```

Start or stop sending a break signal.

# `set_dtr`

```elixir
@spec set_dtr(GenServer.server(), boolean()) :: :ok | {:error, File.posix()}
```

Set or clear the Data Terminal Ready signal.

# `set_rts`

```elixir
@spec set_rts(GenServer.server(), boolean()) :: :ok | {:error, File.posix()}
```

Set or clear the Request To Send signal.

# `signals`

```elixir
@spec signals(GenServer.server()) :: map() | {:error, File.posix()}
```

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_link`

```elixir
@spec start_link(GenServer.options()) :: GenServer.on_start()
```

Start up a UART GenServer.

You usually don't need to pass options here unless you'd like to register a
name for the GenServer.  See `open/3` for opening all of the configuration
options.

# `stop`

```elixir
@spec stop(GenServer.server()) :: :ok
```

Stop the UART GenServer.

# `write`

```elixir
@spec write(GenServer.server(), iodata(), non_neg_integer()) ::
  :ok | {:error, File.posix()}
```

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*