Shadows

Shadows are a virtual copy of controllable physical parameters of your device.

That a mouthful, so let's break it down.

Shadows are a way to represent the state of your device in the cloud, and can be used to control your device remotely. Think of shadows as a lightweight digital twin for your device.

Shadows are defined at the Fleet level, and the shadow schema is shared across all devices in a given fleet.

Shadows are defined using a Protocol Buffer schema, and can be updated by the device itself, a consumer application, the Golain Web App, or APIs.

Let's explore this using an example:

Example: Smart Light

Let's say we have an RGB smart light that can be turned on and off, and have it's color changed. We want to be able to control the light from our mobile app, and also be able to see the current state of the light.

Shadows are perfect for this use case.
We can define a shadow schema that looks like this:

syntax = "proto3";
message Shadow {
    bool on = 1;
    Color color = 2;
}
message Color {
    uint32 red = 1;
    uint32 green = 2;
    uint32 blue = 3;
}