diff --git a/proto/wippersnapper/analogin.options b/proto/wippersnapper/analogin.options new file mode 100644 index 00000000..70ae4cbc --- /dev/null +++ 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 b/proto/wippersnapper/analogin.proto similarity index 54% rename from proto/wippersnapper/analogio.proto rename to proto/wippersnapper/analogin.proto index 0b7eef17..eb66175e 100644 --- a/proto/wippersnapper/analogio.proto +++ b/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 deleted file mode 100644 index 255845bc..00000000 --- a/proto/wippersnapper/analogio.options +++ /dev/null @@ -1,4 +0,0 @@ -# analogio.options -ws.analogio.Add.pin_name max_size: 64 -ws.analogio.Remove.pin_name max_size: 64 -ws.analogio.Event.pin_name max_size: 64 diff --git a/proto/wippersnapper/checkin.proto b/proto/wippersnapper/checkin.proto index 65660d14..4ba7c84c 100644 --- 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 new file mode 100644 index 00000000..70753ac4 --- /dev/null +++ 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 settings = 1; +} \ No newline at end of file diff --git a/proto/wippersnapper/docs/analogio.md b/proto/wippersnapper/docs/analogio.md index 33eff471..f39a03f1 100644 --- 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"
period: 2.0 (seconds)
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"
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 index e236bf5e..e3011184 100644 --- 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 index e05f9239..736b785f 100644 --- 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 index 5b1103a4..6bef3f83 100644 --- 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,7 +317,7 @@ participant IO as Adafruit IO participant Device as WipperSnapper Device participant ADC as ADC Controller -IO->>Device: ws.analogio.B2D {
add: {
pin_name: "A1",
period: 10.0,
read_mode: SENSOR_TYPE_VOLTAGE
}
} +IO->>Device: ws.analogin.B2D {
add: {
pin_name: "A1",
period: 10.0,
read_mode: SENSOR_TYPE_VOLTAGE
}
} Device->>ADC: Configure A1 for voltage reading ADC->>Device: Pin configured, start polling @@ -325,7 +325,7 @@ ADC->>Device: Pin configured, start polling loop Every 10 seconds ADC->>ADC: Read analog value ADC->>Device: Voltage reading - Device->>IO: ws.analogio.D2B {
event: {
pin_name: "A1",
value: 3.7V
}
} + Device->>IO: ws.analogin.D2B {
event: {
pin_name: "A1",
value: 3.7V
}
} 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 index d646b3cb..5deec2a6 100644 --- 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 index 5d5bd4dc..d912f326 100644 --- 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 index 733a5326..fffd3f72 100644 --- 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 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 index c9f622a2..892e0720 100644 --- 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;