Merge pull request #111 from adafruit/add-pixels
Add (updated) Pixels API
This commit is contained in:
Loren Norman
GitHub
commit
30fb6632c2
3 changed files with 211 additions and 0 deletions
120
proto/wippersnapper/pixels/v1/pixels.md
Normal file
120
proto/wippersnapper/pixels/v1/pixels.md
Normal file
|
|
@ -0,0 +1,120 @@
|
|||
# pixels.proto
|
||||
|
||||
This file details the WipperSnapper messaging API for interfacing with a strand of addressable RGB(W) pixels (Adafruit NeoPixel/WS2812b, DotStar/APA102).
|
||||
|
||||
## WipperSnapper Components
|
||||
|
||||
The following component definitions reference `pixels.proto`:
|
||||
* [Adafruit_DotStar](https://github.com/adafruit/Wippersnapper_Components/pull/44)
|
||||
* [Adafruit_NeoPixels](https://github.com/adafruit/Wippersnapper_Components/pull/44)
|
||||
|
||||
## Sequence Diagrams
|
||||
|
||||
### Create: NeoPixel
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
IO-->>Device: PixelsCreateRequest
|
||||
Note over IO, Device: Contains:<br> `pixels_type` of PIXELS_TYPE_NEOPIXEL<br>`pixels_num` according to form<br>`pixels_ordering` according to form<br> `pixels_brightness` according to form <br>`pixels_pin_neopixel` according to form<br> `pixels_pin_dotstar_data` is unused<br>`pixels_pin_dotstar_clock` is unused
|
||||
Device->>IO: PixelsCreateResponse
|
||||
Note over Device,IO: `is_success`, true if init'd OK
|
||||
```
|
||||
|
||||
### Write: NeoPixel
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
IO->>Device: PixelsWriteRequest
|
||||
Note over IO, Device: Contains<br> `pixels_type` of PIXELS_TYPE_NEOPIXEL<br>`pixels_pin_data` according to DB<br>`pixels_color` according to picker<br>
|
||||
```
|
||||
|
||||
### Update: NeoPixel
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
IO->>Device: PixelsDeleteRequest
|
||||
Note over IO, Device: Contains<br> `pixels_type` of PIXELS_TYPE_NEOPIXEL<br>pixels_pin_data according to DB
|
||||
IO-->>Device: PixelsCreateRequest
|
||||
Note over IO, Device: Contains:<br> `pixels_type` of PIXELS_TYPE_NEOPIXEL<br>`pixels_num` according to form<br>`pixels_ordering` according to form<br> `pixels_brightness` of 0<br>`pixels_pin_neopixel` according to form<br> `pixels_pin_dotstar_data` is unused<br>`pixels_pin_dotstar_clock` is unused
|
||||
Device->>IO: PixelsCreateResponse
|
||||
Note over Device,IO: `is_success`, true if init'd OK
|
||||
```
|
||||
|
||||
### Delete: NeoPixel
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
IO->>Device: PixelsDeleteRequest
|
||||
Note over IO, Device: Contains<br> `pixels_type` of PIXELS_TYPE_NEOPIXEL<br>`pixels_pin_data` according to DB
|
||||
```
|
||||
|
||||
### Sync: NeoPixel
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
IO-->>Device: PixelsCreateRequest
|
||||
Note over IO, Device: Contains:<br> `pixels_type` of PIXELS_TYPE_NEOPIXEL<br>`pixels_num` according to form<br>`pixels_ordering` according to form<br> `pixels_brightness` according to form <br>`pixels_pin_neopixel` according to form<br> `pixels_pin_dotstar_data` is unused<br>`pixels_pin_dotstar_clock` is unused
|
||||
Device->>IO: PixelsCreateResponse
|
||||
Note over Device,IO: `is_success`, true if init'd OK
|
||||
IO->>Device: PixelsWriteRequest
|
||||
Note over IO, Device: Contains<br> `pixels_type` of PIXELS_TYPE_NEOPIXEL<br>`pixels_pin_data` according to DB<br>`pixels_color` according to feed's last_value<br>
|
||||
```
|
||||
|
||||
|
||||
### Create: DotStar
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
IO-->>Device: PixelsCreateRequest
|
||||
Note over IO, Device: Contains:<br> `pixels_type` of PIXELS_TYPE_DOTSTAR<br>`pixels_num` according to form<br>`pixels_ordering` according to form<br> `pixels_brightness` according to form <br>`pixels_pin_neopixel` unused<br> `pixels_pin_dotstar_data` according to form<br>`pixels_pin_dotstar_clock` according to form
|
||||
Device->>IO: PixelsCreateResponse
|
||||
Note over Device,IO: `is_success`, true if init'd OK
|
||||
```
|
||||
|
||||
### Write: DotStar
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
IO->>Device: PixelsWriteRequest
|
||||
Note over IO, Device: Contains<br> `pixels_type` of PIXELS_TYPE_DOTSTAR<br>`pixels_pin_data` according to DB<br>`pixels_color` according to picker<br>
|
||||
```
|
||||
|
||||
### Update: DotStar
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
IO->>Device: PixelsDeleteRequest
|
||||
Note over IO, Device: Contains<br> `pixels_type` of PIXELS_TYPE_DOTSTAR<br>pixels_pin_data according to DB
|
||||
IO-->>Device: PixelsCreateRequest
|
||||
Note over IO, Device: Contains:<br> `pixels_type` of PIXELS_TYPE_DOTSTAR<br>`pixels_num` according to form<br>`pixels_ordering` according to form<br> `pixels_brightness` of 0<br>`pixels_pin_neopixel` is unused<br> `pixels_pin_dotstar_data` according to form<br>`pixels_pin_dotstar_clock` according to form
|
||||
Device->>IO: PixelsCreateResponse
|
||||
Note over Device,IO: `is_success`, true if init'd OK
|
||||
```
|
||||
|
||||
### Delete: DotStar
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
IO->>Device: PixelsDeleteRequest
|
||||
Note over IO, Device: Contains<br> `pixels_type` of PIXELS_TYPE_DOTSTAR<br>`pixels_pin_data` according to DB
|
||||
```
|
||||
|
||||
### Sync: DotStar
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
IO-->>Device: PixelsCreateRequest
|
||||
Note over IO, Device: Contains:<br> `pixels_type` of PIXELS_TYPE_DOTSTAR<br>`pixels_num` according to form<br>`pixels_ordering` according to form<br> `pixels_brightness` according to form <br>`pixels_pin_neopixel` is unused<br> `pixels_pin_dotstar_data` according to form<br>`pixels_pin_dotstar_clock` according to form
|
||||
Device->>IO: PixelsCreateResponse
|
||||
Note over Device,IO: `is_success`, true if init'd OK
|
||||
IO->>Device: PixelsWriteRequest
|
||||
Note over IO, Device: Contains<br> `pixels_type` of PIXELS_TYPE_NEOPIXEL<br>`pixels_pin_data` according to DB<br>`pixels_color` according to feed's last_value<br>
|
||||
```
|
||||
71
proto/wippersnapper/pixels/v1/pixels.proto
Normal file
71
proto/wippersnapper/pixels/v1/pixels.proto
Normal file
|
|
@ -0,0 +1,71 @@
|
|||
// SPDX-FileCopyrightText: 2022 Brent Rubell for Adafruit Industries
|
||||
// SPDX-License-Identifier: MIT
|
||||
// Addressable Pixels API for Adafruit WipperSnapper
|
||||
|
||||
syntax = "proto3";
|
||||
|
||||
package wippersnapper.pixels.v1;
|
||||
import "nanopb/nanopb.proto";
|
||||
|
||||
/**
|
||||
* PixelsType defines the type/model of pixel strand.
|
||||
*/
|
||||
enum PixelsType {
|
||||
PIXELS_TYPE_UNSPECIFIED = 0;
|
||||
PIXELS_TYPE_NEOPIXEL = 1;
|
||||
PIXELS_TYPE_DOTSTAR = 2;
|
||||
}
|
||||
|
||||
/**
|
||||
* PixelsOrder defines the color ordering.
|
||||
*/
|
||||
enum PixelsOrder {
|
||||
PIXELS_ORDER_UNSPECIFIED = 0; /** Unspecified color ordering, error. */
|
||||
PIXELS_ORDER_GRB = 1; /** DEFAULT for NeoPixels - Green, Red, Blue */
|
||||
PIXELS_ORDER_GRBW = 2; /** Green, Red, Blue, White */
|
||||
PIXELS_ORDER_RGB = 3; /** Red, Green, Blue */
|
||||
PIXELS_ORDER_RGBW = 4; /** Red, Green, Blue, White */
|
||||
PIXELS_ORDER_BRG = 5; /** DEFAULT for DotStars - Blue, Red, Green */
|
||||
}
|
||||
|
||||
/**
|
||||
* PixelsCreateRequest represents a call from IO to a device.
|
||||
* Creates a strand of addressable pixels.
|
||||
* Initial brightness is always 128.
|
||||
*/
|
||||
message PixelsCreateRequest {
|
||||
PixelsType pixels_type = 1; /** Defines the model/type of pixel strand */
|
||||
uint32 pixels_num = 2; /** Number of pixels attached to strand. */
|
||||
PixelsOrder pixels_ordering = 3; /** Defines the pixel strand's color ordering. */
|
||||
uint32 pixels_brightness = 4; /** Strand brightness, 0 to 255 */
|
||||
string pixels_pin_neopixel = 5 [(nanopb).max_size = 6]; /** Generic pin a NeoPixel strand is connected to. */
|
||||
string pixels_pin_dotstar_data = 6 [(nanopb).max_size = 6]; /** Data pin a DotStar strand is connected to. */
|
||||
string pixels_pin_dotstar_clock = 7 [(nanopb).max_size = 6]; /** Clock pin a DotStar strand is connected to. */
|
||||
}
|
||||
|
||||
/**
|
||||
* PixelsCreateResponse represents response from a WipperSnapper
|
||||
* device to IO after a PixelsCreateRequest call
|
||||
*/
|
||||
message PixelsCreateResponse {
|
||||
bool is_success = 1; /** True if the strand initialized successfully, False otherwise. */
|
||||
}
|
||||
|
||||
/**
|
||||
* PixelCreateRequest represents a call from IO to a device
|
||||
* Deletes a strand of addressable pixels and release the resources and pin.
|
||||
*/
|
||||
message PixelsDeleteRequest {
|
||||
PixelsType pixels_type = 1; /** Defines the model/type of pixel strand */
|
||||
string pixels_pin_data = 2 [(nanopb).max_size = 6]; /** Data pin a strand is connected to. */
|
||||
}
|
||||
|
||||
/**
|
||||
* PixelsWriteRequest represents a call from IO to a device.
|
||||
* Writes to a strand of pixels.
|
||||
*/
|
||||
message PixelsWriteRequest {
|
||||
PixelsType pixels_type = 1; /** Defines the model/type of pixel strand */
|
||||
string pixels_pin_data = 2 [(nanopb).max_size = 6]; /** Data pin a strand is connected to. */
|
||||
uint32 pixels_color = 3; /* 32-bit color value. Most significant byte is white (for RGBW pixels) or ignored (for RGB pixels), next is red, then green, and least significant byte is blue. */
|
||||
}
|
||||
|
|
@ -13,6 +13,7 @@ import "wippersnapper/i2c/v1/i2c.proto";
|
|||
import "wippersnapper/servo/v1/servo.proto";
|
||||
import "wippersnapper/pwm/v1/pwm.proto";
|
||||
import "wippersnapper/ds18x20/v1/ds18x20.proto";
|
||||
import "wippersnapper/pixels/v1/pixels.proto";
|
||||
|
||||
/**
|
||||
* Ds18x20Request represents a Ds18x20 command sent to a device.
|
||||
|
|
@ -89,6 +90,25 @@ message ServoResponse {
|
|||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* PixelsRequest represents the broker's request across the pixels sub-topic.
|
||||
*/
|
||||
message PixelsRequest {
|
||||
option (nanopb_msgopt).submsg_callback = true;
|
||||
oneof payload {
|
||||
wippersnapper.pixels.v1.PixelsCreateRequest req_pixels_create = 1;
|
||||
wippersnapper.pixels.v1.PixelsDeleteRequest req_pixels_delete = 2;
|
||||
wippersnapper.pixels.v1.PixelsWriteRequest req_pixels_write = 3;
|
||||
}
|
||||
}
|
||||
|
||||
message PixelsResponse {
|
||||
option (nanopb_msgopt).submsg_callback = true;
|
||||
oneof payload {
|
||||
wippersnapper.pixels.v1.PixelsCreateResponse resp_pixels_create = 1;
|
||||
}
|
||||
}
|
||||
|
||||
message CreateSignalRequest {
|
||||
option (nanopb_msgopt).submsg_callback = true;
|
||||
oneof payload {
|
||||
|
|
|
|||
Loading…
Reference in a new issue