sdk/fidl/fuchsia.settings/light.fidl

// Copyright 2020 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library fuchsia.settings;

using fuchsia.ui.types;

const MAX_LIGHT_NAME_LENGTH uint8 = 32;

/// Enum describing the possible types of values for controlling a light.
type LightType = strict enum {
    /// This type of light supports setting brightness to a uint8_t value.
    BRIGHTNESS = 1;

    /// This type of light supports setting an RGB value.
    RGB = 2;

    /// Light can only be turned on or off.
    SIMPLE = 3;
};

/// State of a given light.
type LightState = table {
    1: value LightValue;
};

/// Value of a light. Only one of the three values in the union will be present,
/// depending on the light's LightType.
type LightValue = strict union {
    /// Lights with LightType.SIMPLE will have this value.
    1: on bool;

    /// Lights with LightType.BRIGHTNESS will have this value, a floating point
    /// value 0.0 to 1.0 inclusive, where 0.0 means the light is off. Not a
    /// number (NaN), infinity or negative infinity will cause SetLightGroup to
    /// fail with INVALID_VALUE.
    2: brightness float64;

    /// Lights with LightType.RGB will have this value.
    ///
    /// Each color channel should be a value between 0.0 and 1.0 inclusive.
    /// Values outside this range will cause SetLightGroup to fail with
    /// INVALID_VALUE.
    3: color fuchsia.ui.types.ColorRgb;
};

/// Information about a controllable light group. A group may have one or more
/// lights.
type LightGroup = table {
    /// Identifier for this light group, clients should pass this back into the
    /// service to set the group's light values.
    1: name string:MAX_LIGHT_NAME_LENGTH;

    /// True if the light group is enabled and changes will be visible to the
    /// user. False if the light group is forced off by hardware. If the light
    /// group is disabled, its value can still be set, but the change may not be
    /// visible until the light group is back on.
    2: enabled bool;

    /// Defines the acceptable value type for controlling this light group.
    3: type LightType;

    /// States of the lights in this group.
    4: lights vector<LightState>:MAX;
};

type LightError = strict enum {
    /// Call failed for unspecified reasons.
    FAILED = 1;

    /// Call not supported, this setting may not be present on this .
    UNSUPPORTED = 2;

    /// An invalid/unknown light group name was provided.
    INVALID_NAME = 3;

    /// An invalid LightValue was provided that did not match the light group's
    /// LightType or did not match the requirements for the value type.
    INVALID_VALUE = 4;
};

@discoverable
protocol Light {
    /// Fetches information on the controllable light groups on the device.
    /// Returns immediately on first call; subsequent calls return when the
    /// value changes.
    ///
    /// If this call fails, it is considered a fatal error and the channel
    /// will be closed.
    WatchLightGroups() -> (struct {
        groups vector<LightGroup>:MAX;
    });

    /// Fetches information on an individual light group on the device with the
    /// given name. Returns immediately on first call; subsequent calls return
    /// when the value changes.
    ///
    /// If this call fails, it is considered a fatal error and the channel
    /// will be closed. If the failure is due to an invalid light group name,
    /// the channel will be closed with a NOT_FOUND epitaph.
    WatchLightGroup(struct {
        name string:MAX_LIGHT_NAME_LENGTH;
    }) -> (struct {
        group LightGroup;
    });

    /// Sets the values for the lights in the group with the given name.
    ///
    /// If the provided value does not match the light group's type, this
    /// call will fail.
    ///
    /// The requested changes may not take immediate effect if
    /// the light is forced to a certain state by the device's hardware. This
    /// call will still succeed, but the light's value may not change.
    SetLightGroupValues(struct {
        name string:MAX_LIGHT_NAME_LENGTH;
        state vector<LightState>:MAX;
    }) -> () error LightError;
};