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. + +
+ +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. + +
+ +## 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. + +
+Numato devices used by Home Assistant are expected to be exclusive to Home +Assistant and remain permanently connected. +
diff --git a/source/images/supported_brands/numato.png b/source/images/supported_brands/numato.png new file mode 100644 index 00000000000..835c262be3e Binary files /dev/null and b/source/images/supported_brands/numato.png differ