From e9c204bc4914a68a287655ec820b3b5999d45da7 Mon Sep 17 00:00:00 2001
From: clssn <code@clssn.de>
Date: Fri, 1 May 2020 16:38:54 +0200
Subject: [PATCH] Document Numato integration (#12749)

---
 source/_integrations/numato.markdown      | 211 ++++++++++++++++++++++
 source/images/supported_brands/numato.png | Bin 0 -> 13692 bytes
 2 files changed, 211 insertions(+)
 create mode 100644 source/_integrations/numato.markdown
 create mode 100644 source/images/supported_brands/numato.png

diff --git a/source/_integrations/numato.markdown b/source/_integrations/numato.markdown
new file mode 100644
index 00000000000..eeb95e0d5b2
--- /dev/null
+++ b/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>
diff --git a/source/images/supported_brands/numato.png b/source/images/supported_brands/numato.png
new file mode 100644
index 0000000000000000000000000000000000000000..835c262be3e41be64d698337b6dee9c22252f23a
GIT binary patch
literal 13692
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
NFIBZwYL#pv{vVFQuJix^

literal 0
HcmV?d00001