API V2

proto/wippersnapper/analogio/v1/analogio.proto

@@ -0,0 +1,34 @@
+// SPDX-FileCopyrightText: 2023 Brent Rubell, Loren Norman, Tyeth Gundry for Adafruit Industries
+// SPDX-License-Identifier: MIT
+syntax = "proto3";
+
+package wippersnapper.analogio.v1;
+import "nanopb/nanopb.proto";
+import "wippersnapper/sensor/v1/sensor.proto";
+
+message AnalogIOAdd {
+    int32 gpio_num = 1; // correlates with `name` in the JSON
+    float period = 2;
+    AnalogReadMode read_mode = 3;
+
+  /**
+   * Selects the type of value read by an analog pin.
+   * PIN_VALUE: Raw ADC reading.
+   * PIN_VOLTAGE: Calculated voltage reading.
+   */
+  enum AnalogReadMode {
+    ANALOG_READ_MODE_UNSPECIFIED = 0;
+    ANALOG_READ_MODE_PIN_VALUE   = 1;
+    ANALOG_READ_MODE_PIN_VOLTAGE = 2;
+  }
+}
+
+message AnalogIORemove {
+  int32 gpio_num = 1; // correlates with `name` in the JSON
+}
+
+
+message AnalogIOEvent {
+  int32 gpio_num = 1; // correlates with `name` in the JSON
+  wippersnapper.sensor.v1.SensorEvent sensor_event  = 2[(nanopb).max_count = 15]; /** A, optionally repeated, SensorEvent from a sensor. */
+}

proto/wippersnapper/description/v1/description.proto

@@ -10,36 +10,20 @@ import "nanopb/nanopb.proto";
 * CreateDescriptionRequest identifies a device with Adafruit.io WipperSnapper.
 */
 message CreateDescriptionRequest {
-  string machine_name    = 1 [(nanopb).max_size = 64]; /** Identifies client's physical hardware */
-  int32 mac_addr         = 2; /** Client's UID, last 3 bytes of MAC address */
-  int32 usb_vid          = 3; /** Optional, USB Vendor ID */
-  int32 usb_pid          = 4; /** Optional, USB Product ID */
-  Version version        = 5 [deprecated = true, (nanopb).type = FT_IGNORE]; /** Client's library version. */
-  int32 ver_major        = 10 [deprecated = true, (nanopb).type = FT_IGNORE];
-  int32 ver_minor        = 11 [deprecated = true, (nanopb).type = FT_IGNORE];
-  int32 ver_patch        = 12 [deprecated = true, (nanopb).type = FT_IGNORE];
-  string ver_pre_release = 13 [deprecated = true, (nanopb).type = FT_IGNORE, (nanopb).max_size = 6];
-  int32 ver_build        = 14 [deprecated = true, (nanopb).type = FT_IGNORE];
-  string str_version     = 15 [(nanopb).max_size = 20]; /** Library version, as a string */
-
-
-  message Version {
-    uint64 major           = 1 [deprecated = true, (nanopb).type = FT_IGNORE];
-    uint64 minor           = 2 [deprecated = true, (nanopb).type = FT_IGNORE];
-    uint64 micro           = 3 [deprecated = true, (nanopb).type = FT_IGNORE];
-    string label           = 4 [deprecated = true, (nanopb).type = FT_IGNORE];
-    int32 ver_major        = 5 [deprecated = true, (nanopb).type = FT_IGNORE];
-    int32 ver_minor        = 6 [deprecated = true, (nanopb).type = FT_IGNORE];
-    int32 ver_patch        = 7 [deprecated = true, (nanopb).type = FT_IGNORE];
-    string ver_pre_release = 8 [deprecated = true, (nanopb).type = FT_IGNORE];
-    int32 ver_build        = 9 [deprecated = true, (nanopb).type = FT_IGNORE];
-  }
+  string str_version     = 1 [(nanopb).max_size = 20]; /** Library version, as a string */
 }
 
+// TODO: Consider dropping this, and compiling these as a header file (per-board) from the
+// JSON if it is possible to do so.
+
+// This is handled within decodeRegistrationResp(). We would like to drop it completely.
+// TODO: Try the new esp32 function sto detect totoal gpio, analog and reference
+// If that works, we can try to remove WipperSnapper_Register.cpp entirely and use the esp32 func
+// to detect on ESP32 platforms, otherwise add these values into _Boards.h
 /**
-* CreateDescriptionResponse represents a device's specifications.
+* CreateDescription represents a device's specifications.
 */
-message CreateDescriptionResponse {
+message CreateDescription {
   Response response        = 1; /** Specifies if the hardware definition exists on the server. */
   int32 total_gpio_pins    = 2; /** Specifies the number of GPIO pins on the client's physical hardware. */
   int32 total_analog_pins  = 3; /** Specifies the number of analog pins on the client's physical hardware. */
@@ -63,15 +47,3 @@ message CreateDescriptionResponse {
 message RegistrationComplete {
   bool is_complete = 1; /** True if device successfully configured its components, False otherwise. */
 }
-
-// Request the board definition JSON from a device
-// MQTT Topic: `device/ID/description/get`
-message GetDefinitionRequest {
-  string data = 1 [deprecated = true, (nanopb).type = FT_IGNORE]; // Request may be any UTF-8 string value
-}
-
-// Response from Adafruit IO with the JSON board definition as a string
-// MQTT Topic: `device/ID/description/get`
-message GetDefinitionResponse {
-  string board_definition = 1 [deprecated = true, (nanopb).type = FT_IGNORE]; // Response is JSON data encoded as a string
-}

proto/wippersnapper/digitalio/v1/digitalio.proto

@@ -0,0 +1,34 @@
+// SPDX-FileCopyrightText: 2023 Brent Rubell, Loren Norman, Tyeth Gundry for Adafruit Industries
+// SPDX-License-Identifier: MIT
+syntax = "proto3";
+
+package wippersnapper.digitalio.v1;
+import "nanopb/nanopb.proto";
+
+// DigitalInput is a digital input pin.
+message DigitalIOAdd {
+    int32 gpio_num = 1; // correlates with `name` in the JSON
+    DigitalIODirection gpio_direction = 2;
+    float period = 3; /** Optionally specifies the time between measurements, in seconds. */
+    bool value = 4; /** For sync only - optionally send the pin's value. */
+
+    /**
+    * Direction. Specifies the pin's direction, INPUT or OUTPUT.
+    */
+    enum DigitalIODirection {
+        DIRECTION_UNSPECIFIED = 0; /** Invalid Direction from Broker. */
+        DIRECTION_INPUT       = 1; /** Set the pin to behave as an input. */
+        DIRECTION_INPUT_PULL_UP = 2; /** Set the pin to behave as an input. */
+        DIRECTION_OUTPUT      = 3; /** Set the pin to behave as an output. */
+    }
+}
+
+message DigitalIORemove {
+    int32 gpio_num = 1; // correlates with `name` in the JSON
+}
+
+message DigitalIOEvent {
+    int32 gpio_num = 1;
+    bool value = 2;
+}
+

proto/wippersnapper/ds18x20/v1/ds18x20.proto

@@ -6,40 +6,40 @@ syntax = "proto3";
 
 package wippersnapper.ds18x20.v1;
 import "nanopb/nanopb.proto";
-import "wippersnapper/i2c/v1/i2c.proto";
+import "wippersnapper/sensor/v1/sensor.proto";
 
 /**
-* Ds18x20InitRequest represents a request to initialize
+* Ds18x20Add represents a  to initialize
 * a DS18X20 Maxim temperature sensor, from the broker.
 * NOTE: This API only supports ONE DS18X20 device PER OneWire bus.
 */
-message Ds18x20InitRequest {
+message Ds18x20Add {
   string onewire_pin                                                             = 1 [(nanopb).max_size = 5]; /** The desired pin to use as a OneWire bus. */
   int32  sensor_resolution                                                       = 2; /** The desired sensor resolution (9, 10, 11, or 12 bits). */
-  repeated wippersnapper.i2c.v1.I2CDeviceSensorProperties i2c_device_properties  = 3[(nanopb).max_count = 2]; /** Properties for the DS18x20 sensor. */
+  repeated wippersnapper.sensor.v1.SensorType sensor_type  = 3[(nanopb).max_count = 2]; /** Properties for the DS18x20 sensor. */
 }
 
 /**
-* ds18x20InitDs18x20InitResponseResponse represents a device's response
-* to a ds18x20InitRequest message.
+* Ds18x20AddDs18x20AddedResponse represents a device's response
+* to a Ds18x20Add message.
 */
-message Ds18x20InitResponse {
+message Ds18x20Added {
   bool is_initialized  = 1; /** True if the 1-wire bus has been initialized successfully, False otherwise. */
   string onewire_pin   = 2 [(nanopb).max_size = 5]; /** The pin being used as a OneWire bus. */
 }
 
 /**
-* Ds18x20DeInitRequest represents a request to de-initialize a DS18X20
+* Ds18x20Remove represents a  to de-initialize a DS18X20
 * Maxim temperature sensor, from the broker.
 */
-message Ds18x20DeInitRequest {
+message Ds18x20Remove {
   string onewire_pin  = 1 [(nanopb).max_size = 5]; /** The desired onewire bus to de-initialize a DS18x sensor on and release. */
 }
 
 /**
-* Ds18x20DeviceEvent event represents data from **one** DS18X20 sensor.
+* Ds18x20Event event represents data from **one** DS18X20 sensor.
 */
-message Ds18x20DeviceEvent {
+message Ds18x20Event {
   string onewire_pin                                      = 1 [(nanopb).max_size = 5]; /** The desired pin to use as a OneWire bus. */
-  repeated wippersnapper.i2c.v1.SensorEvent sensor_event  = 2 [(nanopb).max_count = 2]; /** The DS18X20's SensorEvent. */
+  repeated wippersnapper.sensor.v1.SensorEvent sensor_event  = 2 [(nanopb).max_count = 2]; /** The DS18X20's SensorEvent. */
 }

proto/wippersnapper/error/v1/error.proto

@@ -0,0 +1,20 @@
+// SPDX-FileCopyrightText: 2023 Brent Rubell, Loren Norman, Tyeth Gundry for Adafruit Industries
+// SPDX-License-Identifier: MIT
+syntax = "proto3";
+
+package wippersnapper.error.v1;
+import "nanopb/nanopb.proto";
+
+// TODO: Add error handling on the device-side to parse error
+// message and either delay on throttle, or disconnect + exponential retry+jitter
+// on ban time
+
+// Jitter should be unique to each device, possibly derived from its clientID
+
+message Error {
+option (nanopb_msgopt).submsg_callback = true; // TODO: Do we need this option field?
+    oneof payload {
+        int32 ban_time = 1;
+        int32 throttle_time = 2;
+    }
+}