adafruit · brentru · May 11, 2026 · May 11, 2026 · May 11, 2026 · May 13, 2026
diff --git a/proto/wippersnapper/analogin.options b/proto/wippersnapper/analogin.options
@@ -0,0 +1,4 @@
+# analogin.options
+ws.analogin.Add.pin_name     max_size: 64
+ws.analogin.Remove.pin_name  max_size: 64
+ws.analogin.Event.pin_name   max_size: 64
diff --git a/proto/wippersnapper/analogio.proto → proto/wippersnapper/analogin.proto b/proto/wippersnapper/analogio.proto → proto/wippersnapper/analogin.proto
@@ -1,7 +1,7 @@
 // SPDX-FileCopyrightText: 2023-2026 Brent Rubell, Loren Norman, Tyeth Gundry for Adafruit Industries
 // SPDX-License-Identifier: MIT
 syntax = "proto3";
-package ws.analogio;
+package ws.analogin;
 import "sensor.proto";
 
 /**
@@ -33,27 +33,27 @@ enum SampleMode {
 }
 
 /**
-* Add adds an analog pin to the device.
+* Add adds an analog input pin to the device.
 */
 message Add {
-  string pin_name          = 1; /** Name of the pin. */
-  float period             = 2; /** Time between reads, in seconds. */
-  ws.sensor.Type read_mode = 3; /** Desired read mode for the pin. */
-  SampleMode sample_mode   = 4; /** Desired sample mode for the pin. */
+  string pin_name              = 1; /** Name of the pin. */
+  float period                 = 2; /** Time between reads, in seconds. */
+  ws.sensor.Type read_mode     = 3; /** Desired read mode for the pin. */
+  SampleMode sample_mode       = 4; /** Desired sample mode for the pin. */
+  float ref_voltage            = 5; /** Reference voltage for the pin, in volts. */
 }
 
 /**
-* Remove removes an analog pin from the device.
+* Remove removes an analog input pin from the device.
 */
 message Remove {
   string pin_name = 1; /** Name of the pin. */
 }
 
-
 /**
-* Event contains a value, sent when an analog pin is read.
+* Event contains a value, sent when an analog input pin is read.
 */
 message Event {
-  string pin_name                   = 1; /** Name of the pin. */
-  ws.sensor.Event value = 2; /** Reading(s) from an analog pin. */
+  string pin_name       = 1; /** Name of the pin. */
+  ws.sensor.Event value = 2; /** Reading(s) from an analog input pin. */
 }
diff --git a/proto/wippersnapper/analogio.options b/proto/wippersnapper/analogio.options
diff --git a/proto/wippersnapper/checkin.proto b/proto/wippersnapper/checkin.proto
@@ -3,7 +3,7 @@
 // Messages for registering new and existing hardware with the Adafruit.io MQTT Broker
 syntax = "proto3";
 package ws.checkin;
-import "analogio.proto";
+import "analogin.proto";
 import "digitalio.proto";
 import "ds18x20.proto";
 import "i2c.proto";
@@ -68,7 +68,7 @@ message Response {
  */
 message ComponentAdds {
   repeated ws.digitalio.Add digitalio_adds    = 1;
-  repeated ws.analogio.Add analogio_adds      = 2;
+  repeated ws.analogin.Add analogin_adds      = 2;
   repeated ws.servo.Add servo_adds            = 3;
   repeated ws.pwm.Add pwm_adds                = 4;
   repeated ws.pixels.Add pixels_adds          = 5;

diff --git a/proto/wippersnapper/config.proto b/proto/wippersnapper/config.proto
@@ -0,0 +1,23 @@
+// SPDX-FileCopyrightText: 2026 Brent Rubell and Loren Norman for Adafruit Industries
+// SPDX-License-Identifier: MIT
+syntax = "proto3";
+package ws.config;
+
+/**
+ * Value represents a configuration value that, may be one of several types.
+ */
+message Value {
+  oneof value {
+    string str_value = 1;
+    int32 int_value = 2;
+    float float_value = 3;
+    bool bool_value = 4;
+  }
+}
+
+/**
+ * Settings represents a collection of configuration settings, where each setting is a key-value pair.
+ */
+message Settings {
+  map<string, Value> settings = 1;
+}
diff --git a/proto/wippersnapper/docs/analogio.md b/proto/wippersnapper/docs/analogio.md
@@ -1,11 +1,11 @@
-# analogio.proto
+# analogin.proto
 
 This file details the WipperSnapper messaging API for reading analog input pins (ADC - Analog to Digital Converter).
 
 ## WipperSnapper Components
 
-The following WipperSnapper components utilize `analogio.proto`:
-* [analogio](https://github.com/adafruit/Wippersnapper_Components/tree/main/components/analogio) - Analog input pins
+The following WipperSnapper components utilize `analogin.proto`:
+* [analogin](https://github.com/adafruit/Wippersnapper_Components/tree/main/components/analogin) - Analog input pins
 
 ## Architecture Overview
 
@@ -41,7 +41,7 @@ participant IO as Adafruit IO
 participant Device as WipperSnapper Device
 participant ADC as ADC Controller
 
-IO->>Device: ws.analogio.B2D { add }
+IO->>Device: ws.analogin.B2D { add }
 Note over IO,Device: pin_name: "A0"<br/>period: 2.0 (seconds)<br/>read_mode: SENSOR_TYPE_VOLTAGE
 
 Device->>ADC: Configure analog pin
@@ -50,7 +50,7 @@ ADC->>Device: Pin configured
 loop Every period seconds
     ADC->>ADC: Read analog value
     ADC->>Device: Convert to requested mode
-    Device->>IO: ws.analogio.D2B { event }
+    Device->>IO: ws.analogin.D2B { event }
     Note over Device,IO: pin_name: "A0"<br/>value: {type: VOLTAGE, value: 3.28}
 end
 ```
@@ -64,7 +64,7 @@ participant IO as Adafruit IO
 participant Device as WipperSnapper Device
 participant ADC as ADC Controller
 
-IO->>Device: ws.analogio.B2D { remove }
+IO->>Device: ws.analogin.B2D { remove }
 Note over IO,Device: pin_name: "A0"
 
 Device->>ADC: Stop reading pin
@@ -79,7 +79,7 @@ ADC->>Device: Pin removed
 Monitor a battery voltage with a voltage divider:
 
 ```
-ws.analogio.B2D { add: {
+ws.analogin.B2D { add: {
   pin_name: "A1",
   period: 10.0,
   read_mode: SENSOR_TYPE_VOLTAGE
@@ -88,7 +88,7 @@ ws.analogio.B2D { add: {
 
 The device sends voltage readings:
 ```
-ws.analogio.D2B { event: {
+ws.analogin.D2B { event: {
   pin_name: "A1",
   value: {type: VOLTAGE, value: 3.7}
 }}
@@ -101,7 +101,7 @@ ws.analogio.D2B { event: {
 Read a potentiometer as a percentage:
 
 ```
-ws.analogio.B2D { add: {
+ws.analogin.B2D { add: {
   pin_name: "A2",
   period: 0.5,
   read_mode: SENSOR_TYPE_UNITLESS_PERCENT
@@ -110,7 +110,7 @@ ws.analogio.B2D { add: {
 
 Returns:
 ```
-ws.analogio.D2B { event: {
+ws.analogin.D2B { event: {
   pin_name: "A2",
   value: {type: UNITLESS_PERCENT, value: 75.3}
 }}
@@ -121,7 +121,7 @@ ws.analogio.D2B { event: {
 Get raw ADC reading for custom calibration:
 
 ```
-ws.analogio.B2D { add: {
+ws.analogin.B2D { add: {
   pin_name: "A3",
   period: 1.0,
   read_mode: SENSOR_TYPE_RAW
@@ -130,7 +130,7 @@ ws.analogio.B2D { add: {
 
 Returns:
 ```
-ws.analogio.D2B { event: {
+ws.analogin.D2B { event: {
   pin_name: "A3",
   value: {type: RAW, value: 2048}
 }}
@@ -141,7 +141,7 @@ ws.analogio.D2B { event: {
 Monitor light levels with a photoresistor voltage divider:
 
 ```
-ws.analogio.B2D { add: {
+ws.analogin.B2D { add: {
   pin_name: "A4",
   period: 5.0,
   read_mode: SENSOR_TYPE_VOLTAGE

diff --git a/proto/wippersnapper/docs/checkin.md b/proto/wippersnapper/docs/checkin.md
@@ -37,7 +37,7 @@ Contains separate repeated fields for each component type to initialize during c
 ```protobuf
 message ComponentAdds {
   repeated ws.digitalio.Add digitalio_adds    = 1;
-  repeated ws.analogio.Add analogio_adds      = 2;
+  repeated ws.analogin.Add analogio_adds      = 2;
   repeated ws.servo.Add servo_adds            = 3;
   repeated ws.pwm.Add pwm_adds                = 4;
   repeated ws.pixels.Add pixels_adds          = 5;

diff --git a/proto/wippersnapper/docs/signal.md b/proto/wippersnapper/docs/signal.md
@@ -22,7 +22,7 @@ message BrokerToDevice {
 
     // Component Interactions
     ws.digitalio.B2D digitalio = 30;
-    ws.analogio.B2D analogio   = 31;
+    ws.analogin.B2D analogin   = 31;
     ws.servo.B2D servo         = 32;
     ws.pwm.B2D pwm             = 33;
     ws.pixels.B2D pixels       = 34;
@@ -51,7 +51,7 @@ message DeviceToBroker {
 
     // Component Interactions
     ws.digitalio.D2B digitalio = 30;
-    ws.analogio.D2B analogio   = 31;
+    ws.analogin.D2B analogin   = 31;
     ws.servo.D2B servo         = 32;
     ws.pwm.D2B pwm             = 33;
     ws.pixels.D2B pixels       = 34;
@@ -115,7 +115,7 @@ Device->>Device: Set pin D13 HIGH
 | 20 | checkin | ws.checkin | Response | Request, Complete |
 | 21 | sleep | ws.sleep | - | - |
 | 30 | digitalio | ws.digitalio | Add, Remove, Write | Event |
-| 31 | analogio | ws.analogio | Add, Remove | Event |
+| 31 | analogin | ws.analogin | Add, Remove | Event |
 | 32 | servo | ws.servo | Add, Remove, Write | Added |
 | 33 | pwm | ws.pwm | Add, Remove, Write | Added |
 | 34 | pixels | ws.pixels | Add, Remove, Write | Added |
@@ -129,4 +129,4 @@ Device->>Device: Set pin D13 HIGH
 
 - [checkin.md](checkin.md) - Device registration and component initialization
 - [wippersnapper_device_overview.md](wippersnapper_device_overview.md) - Complete device flow
-- Individual component docs: [digitalio](digitalio.md), [analogio](analogio.md), [i2c](i2c.md), [display](display.md), [pwm](pwm.md), [servo](servo.md), [pixels](pixels.md), [ds18x20](ds18x20.md), [uart](uart.md)
+- Individual component docs: [digitalio](digitalio.md), [analogin](analogin.md), [i2c](i2c.md), [display](display.md), [pwm](pwm.md), [servo](servo.md), [pixels](pixels.md), [ds18x20](ds18x20.md), [uart](uart.md)
diff --git a/proto/wippersnapper/docs/wippersnapper_device_overview.md b/proto/wippersnapper/docs/wippersnapper_device_overview.md
@@ -11,7 +11,7 @@ This document demonstrates the complete "happy path" flow for a WipperSnapper v2
 - **B2D (BrokerToDevice)** - All commands from Adafruit IO to device
 - **D2B (DeviceToBroker)** - All responses and data from device to Adafruit IO
 
-Each component (digitalio, analogio, i2c, etc.) has its own B2D and D2B envelope messages with specific payloads.
+Each component (digitalio, analogin, i2c, etc.) has its own B2D and D2B envelope messages with specific payloads.
 
 ### Benefits of v2 Architecture
 
@@ -173,7 +173,7 @@ The `ComponentAdds` message contains separate repeated fields for each component
 ```protobuf
 message ComponentAdds {
   repeated ws.digitalio.Add digitalio_adds    = 1;
-  repeated ws.analogio.Add analogio_adds      = 2;
+  repeated ws.analogin.Add analogio_adds      = 2;
   repeated ws.servo.Add servo_adds            = 3;
   repeated ws.pwm.Add pwm_adds               = 4;
   repeated ws.pixels.Add pixels_adds          = 5;
@@ -317,15 +317,15 @@ participant IO as Adafruit IO
 participant Device as WipperSnapper Device
 participant ADC as ADC Controller
 
-IO->>Device: ws.analogio.B2D {<br/>  add: {<br/>    pin_name: "A1",<br/>    period: 10.0,<br/>    read_mode: SENSOR_TYPE_VOLTAGE<br/>  }<br/>}
+IO->>Device: ws.analogin.B2D {<br/>  add: {<br/>    pin_name: "A1",<br/>    period: 10.0,<br/>    read_mode: SENSOR_TYPE_VOLTAGE<br/>  }<br/>}
 
 Device->>ADC: Configure A1 for voltage reading
 ADC->>Device: Pin configured, start polling
 
 loop Every 10 seconds
     ADC->>ADC: Read analog value
     ADC->>Device: Voltage reading
-    Device->>IO: ws.analogio.D2B {<br/>  event: {<br/>    pin_name: "A1",<br/>    value: 3.7V<br/>  }<br/>}
+    Device->>IO: ws.analogin.D2B {<br/>  event: {<br/>    pin_name: "A1",<br/>    value: 3.7V<br/>  }<br/>}
 end
 ```
 
@@ -503,7 +503,7 @@ Adafruit IO                          Device
 | Component | B2D Messages | D2B Messages | Direction |
 |-----------|-------------|--------------|-----------|
 | **digitalio** | add, remove, write | event | Input & Output |
-| **analogio** | add, remove | event | Input only |
+| **analogin** | add, remove | event | Input only |
 | **i2c** | bus_scan, device_add_replace, device_remove | bus_scanned, device_added_replaced, device_removed, device_event | Input & Output |
 | **display** | Add, Remove, Write | AddedOrReplaced, Removed | Output only |
 | **pwm** | add, remove, write | - | Output only |
@@ -723,7 +723,7 @@ sequenceDiagram
   - [display.md](display.md) - Display controllers with multiple interface types
   - [spi.md](spi.md) - Shared SPI bus and device pin configuration
   - [digitalio.md](digitalio.md) - Digital GPIO with B2D/D2B
-  - [analogio.md](analogio.md) - Analog input with B2D/D2B
+  - [analogin.md](analogin.md) - Analog input with B2D/D2B
   - [pwm.md](pwm.md), [servo.md](servo.md), [pixels.md](pixels.md), etc.
 
 - For hardware definitions:

diff --git a/proto/wippersnapper/error.proto b/proto/wippersnapper/error.proto
@@ -13,7 +13,7 @@ import "uart.proto";
 enum ComponentType {
   COMPONENT_TYPE_UNSPECIFIED = 0; /** Invalid Component Type. */
   COMPONENT_TYPE_DIGITALIO   = 1; /** Digital IO Component. */
-  COMPONENT_TYPE_ANALOGIO    = 2; /** Analog IO Component. */
+  COMPONENT_TYPE_ANALOGIN    = 2; /** Analog In Component. */
   COMPONENT_TYPE_PWM         = 3; /** PWM Component. */
   COMPONENT_TYPE_SERVO       = 4; /** Servo Component. */
   COMPONENT_TYPE_PIXELS      = 5; /** Pixels Component. */

diff --git a/proto/wippersnapper/expander.proto b/proto/wippersnapper/expander.proto
@@ -25,28 +25,28 @@ message D2B {
 }
 
 /**
-* Add adds an expander to the hardware.
+* Add adds an expander component to the hardware.
 */
 message Add {
-  i2c.Add cfg_i2c = 1; /** I2C configuration for the expander. */
+  i2c.Add cfg_i2c             = 1; /** I2C configuration for the expander. */
 }
 
 /**
-* Added represents a message from the hardware indicating an expander was added.
+* Added represents a message from the hardware indicating an expander component was added.
 */
 message Added {
   i2c.Added response_i2c = 1; /** I2C configuration response. */
 }
 
 /**
-* Remove removes an analog pin from the hardware.
+* Remove removes an expander component from the hardware.
 */
 message Remove {
   i2c.Remove cfg_i2c = 1; /** I2C configuration for the expander to remove. */
 }
 
 /**
-* Removed represents a message from the device indicating an expander was removed.
+* Removed represents a message from the device indicating an expander component was removed.
 */
 message Removed {
   i2c.Removed response_i2c = 1; /** I2C configuration response. */

diff --git a/proto/wippersnapper/i2c.proto b/proto/wippersnapper/i2c.proto
@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: MIT
 syntax = "proto3";
 package ws.i2c;
+import "config.proto";
 import "sensor.proto";
 
 /**
@@ -108,11 +109,10 @@ message Descriptor {
 */
 message Add {
   Descriptor descriptor             = 1; /** The I2c device's address and metadata. */
-  /** The I2c device's name, MUST MATCH the name on the JSON
-   *  definition file on the Wippersnapper_Components repo. */
-  string name                       = 2;
+  string name                       = 2; /** The I2c device's name. **/
   float period                      = 3; /** The desired period to update the I2c device's sensor(s), in seconds. */
   map<uint32, ws.sensor.Type> types = 4; /** SI Types for each sensor on the I2c device. */
+  ws.config.Settings settings       = 5; /** Additional device configuration options. **/
 }
 
 /**

diff --git a/proto/wippersnapper/signal.proto b/proto/wippersnapper/signal.proto
@@ -5,7 +5,7 @@ package ws.signal;
 import "error.proto";
 import "expander.proto";
 import "checkin.proto";
-import "analogio.proto";
+import "analogin.proto";
 import "digitalio.proto";
 import "display.proto";
 import "ds18x20.proto";
@@ -34,7 +34,7 @@ message BrokerToDevice {
 
     // Component Interactions
     ws.digitalio.B2D digitalio = 30;
-    ws.analogio.B2D analogio   = 31;
+    ws.analogin.B2D analogin   = 31;
     ws.servo.B2D servo         = 32;
     ws.pwm.B2D pwm             = 33;
     ws.pixels.B2D pixels       = 34;
@@ -64,7 +64,7 @@ message DeviceToBroker {
 
     // Component Interactions
     ws.digitalio.D2B digitalio = 30;
-    ws.analogio.D2B analogio   = 31;
+    ws.analogin.D2B analogin   = 31;
     ws.servo.D2B servo         = 32;
     ws.pwm.D2B pwm             = 33;
     ws.pixels.D2B pixels       = 34;