newtmgr conn
-------------

Manage newtmgr connection profiles.

.. contents::
  :local:
  :depth: 2

Usage:
^^^^^^

.. code-block:: console

    newtmgr conn [command] [flags]

Global Flags:
^^^^^^^^^^^^^

.. code-block:: console

      -c, --conn string       connection profile to use
      -l, --loglevel string   log level to use (default "info")
          --name string       name of target BLE device; overrides profile setting
      -t, --timeout float     timeout in seconds (partial seconds allowed) (default 10)
      -r, --tries int         total number of tries in case of timeout (default 1)

Description
^^^^^^^^^^^

The conn command provides subcommands to add, delete, and view connection profiles. A connection profile specifies
information on how to connect and communicate with a remote device. Newtmgr commands use the information from a
connection profile to send newtmgr requests to remote devices.

Add Sub-Command
~~~~~~~~~~~~~~~

The ``newtmgr conn add <conn_profile> <var-name=value ...>`` command creates a connection profile named
``conn_profile``. The command requires the ``conn_profile`` name and a list of, space separated,
var-name=value pairs.

The var-names are: ``type``, and ``connstring``. The valid values for each var-name parameter are:

* ``type``:
  The connection type. Valid values are:

  - **serial**: Newtmgr protocol over a serial connection.
  - **oic_serial**: OIC protocol over a serial connection.
  - **udp**:newtmgr protocol over UDP.
  - **oic_udp**: OIC protocol over UDP.
  - **ble** newtmgr protocol over BLE. This type uses native OS BLE support
  - **oic_ble**: OIC protocol over BLE. This type uses native OS BLE support.
  - **bhd**: newtmgr protocol over BLE. This type uses the blehostd implemenation.
  - **oic_bhd**: OIC protocol over BLE. This type uses the blehostd implementation.

  **Note:** newtmgr does not support BLE on Windows.

* ``connstring``:
  The physical or virtual address for the connection. The format of the ``connstring`` value depends
  on the connection ``type`` value as follows:

  - **serial** and **oic_serial**: A quoted string with two, comma separated, ``attribute=value`` pairs.
    The attribute names and value format for each attribute are:

    * ``dev``: (Required) The name of the serial port to use. For example: **/dev/ttyUSB0** on a Linux platform or
      **COM1** on a Windows platform .
    * ``baud``: (Optional) A number that specifies the buad rate for the connection. Defaults to **115200** if the
      attribute is not specified.

    Example: ``connstring="dev=/dev/ttyUSB0, baud=9600"``
    **Note:** The 1.0 format, which only requires a serial port name, is still supported. For example, ``connstring=/dev/ttyUSB0``.

  - **udp** and **oic_udp**: The peer ip address and port number that the newtmgr or oicmgr on the remote device is
    listening on. It must be of the form: **[<ip-address>]:<port-number>**.

  - **ble** and **oic_ble**: The format is a quoted string of, comma separated, ``attribute=value`` pairs. The attribute
    names and the value for each attribute are:

    * ``peer_name``: A string that specifies the name the peer BLE device advertises. **Note**: If this attribute is
      specified, you do not need to specify a value for the ``peer_id`` attribute.

    * ``peer_id``: The peer BLE device address or UUID. The format depends on the OS that the newtmgr tool is running on:

        **Linux**: 6 byte BLE address. Each byte must be a hexidecimal number and separated by a colon.

        **MacOS**: 128 bit UUID.

      **Note**: This value is only used when a peer name is not specified for the connection profile or with the
      ``--name`` flag option.

    * ``ctlr_name``: (Optional) Controller name. This value depends on the OS that the newtmgr tool is running on.


    **Notes**:

    * You must specify ``connstring=" "`` if you do not specify any attribute values.

    * You can use the ``--name`` flag to specify a device name when you issue a newtmgr command that communicates with
      a BLE device. You can use this flag to override or in lieu of specifying a ``peer_name`` or ``peer_id`` attribute
      in the connection profile.

  - **bhd** and **oic_bhd**: The format is a quoted string of, comma separated, ``attribute=value`` pairs. The
    attribute names and the value format for each attribute are:

    * ``peer_name``: A string that specifies the name the peer BLE device advertises.
      **Note**: If this attribute is specified, you do not need to specify values for the ``peer_addr`` and
      ``peer_addr_type`` attributes.

    * ``peer_addr``: A 6 byte peer BLE device address. Each byte must be a hexidecimal number and separated by a colon.
      You must also specify a ``peer_addr_type`` value for the device address.
      **Note:** This value is only used when a peer name is not specified for the connection profile or with the
      ``--name`` flag option.

    * ``peer_addr_type``: The peer address type. Valid values are:

      - **public**: Public address assigned by the manufacturer.
      - **random**: Static random address.
      - **rpa_pub**: Resolvable Private Address with public identity address.
      - **rpa_rnd**: Resolvable Private Address with static random identity address.

      **Note:** This value is only used when a peer name is not specified for the connection profile or with the
      ``--name`` flag option.

    * ``own_addr_type``: (Optional) The address type of the BLE controller for the host that the newtmgr tool is
      running on. See the ``peer_addr_type`` attribute for valid values. Defaults to **random**.

    * ``ctlr_path``: The path of the port that is used to connect the BLE controller to the host that the newtmgr tool is
      running on.

  **Note**: You can use the ``--name`` flag to specify a device name when you issue a newtmgr command that communicates
  with a BLE device. You can use this flag to override or in lieu of specifying a ``peer_name`` or ``peer_addr``
  attribute in the connection profile.

Delete Sub-Command
~~~~~~~~~~~~~~~~~~

The ``newtmgr conn delete <conn_profile>`` command deletes the ``conn_profile`` connection profile.

Show Sub-Command
~~~~~~~~~~~~~~~~

The ``newtmgr conn show [conn_profile]`` command shows the information for the ``conn_profile`` connection profile.
It shows information for all the connection profiles if ``conn_profile`` is not specified.

Examples
^^^^^^^^

+---------------+-------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Sub-command   | Usage                                                                                                                   | Explanation                                                                                                                                                                                                                                                                           |
+===============+=========================================================================================================================+=======================================================================================================================================================================================================================================================================================+
| add           | ``newtmgr conn add myserial02 type=oic_serial connstring=/dev/ttys002``                                                 | Creates a connection profile, named ``myserial02``, to communicate over a serial connection at 115200 baud rate with the oicmgr on a device that is connected to the host on port /dev/ttys002.                                                                                       |
+---------------+-------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| add           | ``newtmgr conn add myserial03 type=serial connstring="dev=/dev/ttys003, baud=57600"``                                   | Creates a connection profile, named ``myserial03``, to communicate over a serial connection at 57600 baud rate with the newtmgr on a device that is connected to the host on port /dev/ttys003.                                                                                       |
+---------------+-------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| add           | ``newtmgr conn add myudp5683 type=oic_udpconnstring=[127.0.0.1]:5683``                                                  | Creates a connection profile, named ``myudp5683``, to communicate over UDP with the oicmgr on a device listening on localhost and port 5683.                                                                                                                                          |
+---------------+-------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| add           | ``newtmgr conn add mybleprph type=ble connstring="peer_name=nimble-bleprph"``                                           | Creates a connection profile, named ``mybleprph``, to communicate over BLE, using the native OS BLE support, with the newtmgr on a device named ``nimble-bleprph``.                                                                                                                   |
+---------------+-------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| add           | ``newtmgr conn add mybletype=ble connstring=" "``                                                                       | Creates a connection profile, named ``myble``, to communicate over BLE, using the native OS BLE support, with the newtmgr on a device. You must use the ``--name`` flag to specify the device name when you issue a newtmgr command that communicates with the device.                |
+---------------+-------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| add           | ``newtmgr conn add myblehostd type=oic_bhd connstring="peer_name=nimble-bleprph,ctlr_path=/dev/cu.usbmodem14221"``      | Creates a connection profile, named ``myblehostd``, to communicate over BLE, using the blehostd implementation, with the oicmgr on a device named ``nimble-bleprph``. The BLE controller is connected to the host on USB port /dev/cu.usbmodem14211 and uses static random address.   |
+---------------+-------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| delete        | ``newtmgr conn delete myserial02``                                                                                      | Deletes the connection profile named ``myserial02``                                                                                                                                                                                                                                   |
+---------------+-------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| delete        | ``newtmgr conn delete myserial02``                                                                                      | Deletes the connection profile named ``myserial02``                                                                                                                                                                                                                                   |
+---------------+-------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| show          | ``newtmgr conn show myserial01``                                                                                        | Displays the information for the ``myserial01`` connection profile.                                                                                                                                                                                                                   |
+---------------+-------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| show          | ``newtmgr conn show``                                                                                                   | Displays the information for all connection profiles.                                                                                                                                                                                                                                 |
+---------------+-------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+