firmata docs analog I/O, deprecate arduino, home-assistant/core#40369 (#14580)

source/_integrations/arduino.markdown

@@ -12,6 +12,12 @@ ha_codeowners:
 ha_domain: arduino
 ---
 
+<div class='note warning'>
+
+This integration is deprecated. Please move to the [Firmata integration](/integrations/firmata).
+
+</div>
+
 The [Arduino](https://www.arduino.cc/) device family are microcontroller boards that are often based on the ATmega328 chip. They come with digital input/output pins (some can be used as PWM outputs), analog inputs, and a USB connection.
 The equipment depends on the [type](https://www.arduino.cc/en/Main/Products) of the board. The most common ones are the Arduino Uno and the Arduino Leonardo with 14 digital input/output pins and 6 analog input pins.
 

source/_integrations/firmata.markdown

@@ -4,6 +4,8 @@ description: Connect Arduino-compatible boards within Home Assistant
 ha_category:
   - DIY
   - Binary Sensor
+  - Light
+  - Sensor
   - Switch
 ha_release: 0.114
 ha_iot_class: Local Push
@@ -12,13 +14,15 @@ ha_codeowners:
 ha_domain: firmata
 ---
 
-[Firmata](https://github.com/firmata/protocol) can be used to add digital inputs and outputs to Home Assistant. Currently, this component supports high/low digital inputs and outputs. This allows for buttons, switches, motion detectors, relay control, etc. The component can currently connect to a Firmata board via serial or serial over USB.
+[Firmata](https://github.com/firmata/protocol) can be used to add analog and digital inputs and outputs to Home Assistant. This allows for buttons, switches, motion detectors, relay control, sensors, potentiometers, dimmers, etc. The component can currently connect to a Firmata board via serial or serial over USB.
 
-The Firmata protocol is a standard protocol for microcontrollers. Most of these boards are support digital and analog inputs and outputs. [Arduino](https://www.arduino.cc/) and Arduino-compatible microcontroller development boards are the most popular boards to use with Firmata.
+The Firmata protocol is a standard protocol for microcontrollers. Most of these boards support digital and analog inputs and outputs. [Arduino](https://www.arduino.cc/) and Arduino-compatible microcontroller development boards are the most popular boards to use with Firmata.
 
 There is currently support for the following device types within Home Assistant:
 
 - [Binary Sensor](#binary_sensor)
+- [Light](#lights)
+- [Sensor](#sensors)
 - [Switch](#switches)
 
 ## Configuration
@@ -74,13 +78,13 @@ switches:
       required: true
       type: string
     pin:
-      description: The digital pin number on the board.
+      description: The digital or analog pin number on the board.
       required: true
-      type: integer
+      type: [integer, string]
     pin_mode:
-      description: The digital pin output mode. For switches, this must be set to `OUTPUT`. No other output modes are currently implemented.
+      description: The digital or analog pin output mode. For switches, this must be set to `OUTPUT`. No other output modes are currently implemented.
       required: true
-      type: integer
+      type: string
     initial:
       description: The initial output of the pin after initialization. Note that this is inverted if `negate` is enabled.
       required: false
@@ -91,8 +95,8 @@ switches:
       required: false
       default: False
       type: boolean
-binary_sensor:
+lights:
-  description: Digital high/low input to configure
+  description: PWM/Analog outputs to configure
   required: false
   type: list
   keys:
@@ -101,24 +105,84 @@ binary_sensor:
       required: true
       type: string
     pin:
-      description: The digital pin number on the board.
+      description: The digital or analog pin number on the board. Note that most boards do not support analog or PWM output on all digital and analog pins.
       required: true
-      type: integer
+      type: [integer, string]
     pin_mode:
-      description: The digital pin input mode. Supported modes are `INPUT` and `PULLUP`. Check your board specifications to see which pins have optional internal pullups available.
+      description: The digital or analog pin output mode. For lights, this must be set to `PWM`. No other output modes are currently implemented.
       required: true
+      type: string
+    initial:
+      description: The initial output of the pin after initialization. This should be a Home Assistant-like value from 0 to 255; this value is then plugged into the `minimum`/`maximum` scaling (if configured).
+      required: false
+      default: 0
       type: integer
+    minimum:
+      description: The minimum PWM/analog value to send (inclusive). This is the lowest allowed value that the pin will output. The Home Assistant brightness value (0 to 255) will be scaled with this value as the lower value of the range.
+      required: false
+      default: 0
+      type: integer
+    maximum:
+      description: The maximum PWM/analog value to send (inclusive). This is the highest allowed value that the pin will output. The Home Assistant brightness value (0 to 255) will be scaled with this value as the higher value of the range.
+      required: false
+      default: 255
+      type: integer
+binary_sensor:
+  description: Digital or analog high/low input to configure
+  required: false
+  type: list
+  keys:
+    name:
+      description: The name of the entity to create in Home Assistant
+      required: true
+      type: string
+    pin:
+      description: The digital or analog pin number on the board.
+      required: true
+      type: [integer, string]
+    pin_mode:
+      description: The digital or analog pin input mode. Supported modes are `INPUT` and `PULLUP`. Check your board specifications to see which pins have optional internal pullups available.
+      required: true
+      type: string
     negate:
-      description: Flips the input of the digital pin
+      description: Flips the input of the digital or analog pin
       required: false
       default: False
       type: boolean
+sensor:
+  description: Analog input to configure
+  required: false
+  type: list
+  keys:
+    name:
+      description: The name of the entity to create in Home Assistant
+      required: true
+      type: string
+    pin:
+      description: The analog pin number on the board. This should be in the form `A0`, `A1`, etc.
+      required: true
+      type: string
+    pin_mode:
+      description: The analog pin input mode. For sensors, this must be set to `ANALOG`. No other input modes are currently implemented.
+      required: true
+      type: string
+    differential:
+      description: Minimum difference in value to update. The absolute value of the difference between the old and new value must be greater than or equal to this option for the update to register in Home Assistant. **This is set to `40` by default to prevent an unconnected pin from clogging the Home Assistant history with updates.** Set this to `1` to register all updates in Home Assistant. Updates are registered as fast as the board can send them (very fast). The minimum value that may be set is `1`.
+      required: false
+      default: 40
+      type: integer
 {% endconfiguration %}
 
 <div class='note'>
 If you double-configure a pin, the integration will fail to configure the second one that it attempts to set up and will log an error.
 </div>
 
+<div class='note'>
+
+To invert/negate a light, set the `maximum` to `0` and the `minimum` to `255`.
+
+</div>
+
 ```yaml
 # Example firmata configuration.yaml entry
 firmata:
@@ -133,11 +197,26 @@ firmata:
         pin_mode: OUTPUT
         pin: 5
         initial: true
-      - name: my_light
+      - name: my_light2
         pin_mode: OUTPUT
-        pin: 6
+        pin: A6
         initial: true
         negate: true
+    lights:
+      - name: my_dimmable_light
+        pin_mode: PWM
+        pin: 6
+      - name: my_subset_light
+        pin_mode: PWM
+        pin: 10
+        initial: 0
+        minimum: 127
+        maximum: 200
+      - name: my_inverted_light
+        pin_mode: PWM
+        pin: 11
+        minimum: 255
+        maximum: 0
     binary_sensors:
       - name: my_motion
         pin_mode: INPUT
@@ -146,4 +225,13 @@ firmata:
         pin_mode: PULLUP
         pin: 3
         negate: true
+      - name: my_other_door
+        pin_mode: INPUT
+        pin: A1
+        negate: true
+    sensors:
+      - name: my_sensor
+        pin: A0
+        pin_mode: ANALOG
+        differential: 40
 ```