Document Numato integration (#12749)

source/_integrations/numato.markdown

@@ -0,0 +1,211 @@
+---
+title: Numato USB GPIO Expander
+description: Instructions on how to integrate a Numato GPIO expander into Home Assistant.
+ha_category:
+  - DIY
+  - Binary Sensor
+  - Sensor
+  - Switch
+logo: numato.png
+ha_release: "0.110"
+ha_iot_class: Local Push
+ha_domain: numato
+---
+
+The `numato` integration is the base for all related GPIO platforms of the
+[Numato 32 Port USB GPIO expander](https://numato.com/product/32-channel-usb-gpio-module-with-analog-inputs):
+
+- [Binary Sensor](#binary-sensor)
+- [Sensor](#sensor)
+- [Switch](#switch)
+
+The whole configuration of all Numato devices is located in the general setup
+of this integration. The following minimalistic example configures a couple of
+binary_sensor, switch and sensor ports for a single device with ID 0.
+
+```yaml
+numato:
+  devices:
+    - id: 0
+      binary_sensors:
+        ports:
+          2: Window Livingroom Open
+          3: Window Livingroom Glassbreak
+          4: Doorbell
+      sensors:
+        ports:
+          1:
+            name: Soil Moisture Ficus
+      switches:
+        ports:
+          5: Relay Light Outdoor
+          6: Relay Circulation Pump
+          7: Door Opener
+```
+
+{% configuration %}
+discover:
+  description: List of OS device files (/dev/...) to try during discovery
+  required: false
+  default: List of /dev/ttyACM0 .. /dev/ttyACM9
+  type: list
+devices:
+  description: List of Numato 32 Port USB GPIO devices.
+  required: true
+  type: list
+  keys:
+    id:
+      description: ID configured in the device (not the Linux device since this can change).
+      required: true
+      type: integer
+    binary_sensors:
+      description: Configuration of ports for the `binary_sensor` platform
+      type: map
+      keys:
+        invert_logic:
+          description: Whether to invert the logic, so a high voltage level is interpreted as false.
+          required: false
+          default: false
+          type: boolean
+        ports:
+          description: Map of port numbers to names.
+          required: true
+          type: map
+          keys:
+            "port: name":
+              description: The port numbers and corresponding names.
+              required: true
+              type: string
+    sensors:
+      description: Configuration of ports for the `sensor` platform
+      type: map
+      keys:
+        ports:
+          description: Map of port numbers to ADC configurations.
+          required: true
+          type: map
+          keys:
+            "port: adc_config":
+              description: The port number and corresponding ADC configuration.
+              required: true
+              type: map
+              keys:
+                name:
+                  description: Name of the ADC sensor port.
+                  required: true
+                  type: string
+                source_range:
+                  description: Range within the ADC's resolution to map values from.
+                  required: false
+                  default: [0, 1024]
+                  type: list
+                destination_range:
+                  description: Range to map values from the source range to in a linear fashion.
+                  required: false
+                  default: [0.0, 100.0]
+                  type: list
+                unit:
+                  description: Unit of the destination values.
+                  required: false
+                  type: string
+                  default: \%
+    switches:
+      description: Configuration of ports for the `sensor` platform
+      type: map
+      keys:
+        invert_logic:
+          description: Whether to invert the logic, so a value of true leads to a low voltage level at the output.
+          required: false
+          default: false
+          type: boolean
+        ports:
+          description: Map of port numbers to names.
+          required: true
+          type: map
+          keys:
+            "port: name":
+              description: The port numbers and corresponding names.
+              required: true
+              type: string
+{% endconfiguration %}
+
+## Binary Sensor
+
+The `numato` binary_sensor platform allows you to operate the GPIOs of your
+[Numato](https://numato.com) 32 port USB GPIO expander in binary input mode.
+
+<div class='note warning'>
+
+As the Numato devices do not have internal pull-up or pull-down circuitry,
+be careful not to destroy a port by creating a short circuit. Refer to the
+[Numato documentation](https://numato.com/docs/32-channel-usb-gpio-module-with-analog-inputs/#gpio-with-switches-8)
+on how to connect a switch to an input port, for example.
+
+</div>
+
+## Sensor
+
+The `numato` sensor platform allows you to operate some GPIOs of your USB GPIO
+expander in analog input mode.
+
+The Numato device has a number of built-in analog-digital-converters (ADCs) to
+convert a voltage level between VCC and GND into a 10-bit integer value. Read
+the [IO Ports](#io-ports) section for constraints on the ports to use.
+
+By default, the ADC's whole 10-bit range will be mapped to a float value between
+0.0 and 1.0. Use the optional `source_range` to map from a specific range and
+the `destination_range` to specify the value range to represent the entity
+state.
+
+## Switch
+
+The `numato` switch platform allows you to operate the GPIOs of your
+[Numato](https://numato.com) 32 port USB GPIO expander in output mode.
+
+## IO Ports
+
+The IO port numbers used in this configuration refer to the port numbers
+printed on the PCB. Note that the Sensor platform can be configured on ports
+1-7 only. These are the only ports on the 32 port device equipped with an ADC.
+
+For details about the GPIO layout, take a look at the [Numato 32 GPIO
+documentation](https://numato.com/docs/32-channel-usb-gpio-module-with-analog-inputs).
+
+## Device IDs
+
+This integration uses a internal device ID to identify the device, which is
+_not_ the Linux device path. The Linux device path (e.g., `/dev/ttyACM0`) can
+change, for example, when you disconnect and re-connect the device or if you
+connect the device to a different USB port.
+
+The internal device ID is 0 by default. If you have only one device, you should
+not need to care about changing it. If you have multiple devices, their IDs are
+shown in the console log during startup of Home Assistant.
+
+### Configure the Device ID
+
+Configure your Numato device's ID with the following steps. Though you can use
+any terminal emulator to connect to and communicate with your device, the
+following steps are based on using _GNU Screen_. On a Debian or Ubuntu-based OS
+install _Screen_ like `sudo apt install screen`.
+
+1. Plug in only the one device to assign an id to so it'll get /dev/ttyACM0
+2. Wait a couple of seconds as your Linux OS may be trying to identify the
+   device as a Modem right after plugging it in
+3. Run `screen /dev/ttyACM0`
+4. Type `id get` to see the current ID
+5. Type `id set 00000005` and hit enter to assign ID 5
+6. Type `id get` to validate and expect `00000005` as a reply
+7. Quit screen with: Ctrl-a + \ and confirm with `y`
+
+Note that during communication with the device the ID values are strictly 32
+bit hexadecimal numbers (8 hex digits) with leading `0` padding.
+
+Hint: It is a good practice to put sticky labels with the IDs onto the PCBs in
+order to avoid confusion of devices and their port configuration since this
+could easily destroy your device.
+
+<div class='note warning'>
+Numato devices used by Home Assistant are expected to be exclusive to Home
+Assistant and remain permanently connected.
+</div>