// 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.factory.lowpan;

using fuchsia.lowpan.device;

alias InterfaceName = fuchsia.lowpan.device.InterfaceName;
alias ServiceError = fuchsia.lowpan.device.ServiceError;

/// Protocol for sending factory commands to a LoWPAN device.
///
/// Not to be confused with `FactoryDriver`.
///
/// This protocol is implemented by LoWPAN drivers and used by client tools that need to issue
/// factory commands. It is obtained from calling `FactoryLookup.Lookup()`.
protocol FactoryDevice {
    /// Send a proprietary manufacturing command to the device and return the response.
    ///
    /// This method is intended to be used to facilitate device testing on the assembly line and is
    /// typically only used during device manufacturing.
    ///
    /// Commands are given as strings (command + arguments) and the response is also a string. The
    /// usage and format of the commands is dependent on the firmware on the LoWPAN device.
    ///
    /// When finished sending manufacturing commands, call `fuchsia.lowpan.test.DeviceTest.reset()`
    /// to return the device to normal behavior.
    SendMfgCommand(struct {
        command string:2000;
    }) -> (struct {
        response string:2000;
    });
};

/// Protocol for looking up the LoWPAN factory protocol for a LoWPAN interface.
///
/// This protocol is implemented by the LoWPAN service and used by client tools that need to issue
/// factory commands.
@discoverable
protocol FactoryLookup {
    /// Connects the the associated `FactoryDevice` API for the given LoWPAN interface name.
    Lookup(resource struct {
        name InterfaceName;
        device_factory server_end:FactoryDevice;
    }) -> (struct {}) error ServiceError;
};

/// Protocol representing a LoWPAN driver instance that can serve `FactoryDevice` instances.
///
/// Not to be confused with `FactoryDevice`.
///
/// This protocol is implemented by LoWPAN drivers and used by the LoWPAN service when
/// handling calls to `FactoryLookup.Lookup()`. It is registered with the service via
/// a call to `FactoryRegister.Register()`.
protocol FactoryDriver {
    /// Used to obtain a `FactoryDevice` protocol instance.
    GetFactoryDevice(resource struct {
        device_factory server_end:FactoryDevice;
    });
};

/// Protocol for registering the factory instance of a LoWPAN driver with the LoWPAN service.
///
/// This protocol is implemented by the LoWPAN service and used by LoWPAN drivers.
@discoverable
protocol FactoryRegister {
    /// Registers the given LoWPAN device factory API with the LoWPAN Service
    /// using the given interface name.
    ///
    /// The provided `FactoryDriver` will be used to connect requests made via
    /// `FactoryLookup.Lookup()` for `FactoryDevice`.
    Register(resource struct {
        name InterfaceName;
        driver client_end:FactoryDriver;
    }) -> (struct {}) error ServiceError;
};