estop.proto

// Copyright (c) 2019 Boston Dynamics, Inc.  All rights reserved.
//
// Downloading, reproducing, distributing or otherwise using the SDK Software
// is subject to the terms and conditions of the Boston Dynamics Software
// Development Kit License (20191101-BDSDK-SL).

syntax = "proto3";

package bosdyn.api;

option java_outer_classname = "EstopProto";

import "bosdyn/api/header.proto";
import "google/protobuf/duration.proto";

/// An API client to the robot software-estop system.
message EstopEndpoint {
    /// Role of this endpoint. Should be user-friendly, e.g. "OCU"
    string role = 1;

    /// Name of this endpoint. Specifies a thing to fill the given role, e.g. "patrol-ocu01"
    string name = 2;

    /// Unique ID assigned by the server.
    string unique_id = 3;

    /// Maximum delay between challenge and response for this endpoint prior to soft power off
    /// handling. After timeout seconds has passed, the robot will try to get to a safe state prior
    /// to disabling motor power. The robot response is equivalent to an ESTOP_LEVEL_SETTLE_THEN_CUT
    /// which may involve the robot sitting down in order to prepare for disabling motor power.
    google.protobuf.Duration timeout = 4;

    /// Optional maximum delay between challenge and response for this endpoint prior to disabling
    /// motor power. After cut_power_timeout seconds has passed, motor power will be disconnected
    /// immediately regardless of current robot state. If this value is not set robot will default
    /// to timeout plus a nominal expected duration to reach a safe state. In practice this
    /// is typically 3-4 seconds. The response is equivalent to an ESTOP_LEVEL_CUT.
    google.protobuf.Duration cut_power_timeout = 5;
}

/// The state of the estop system.
enum EstopStopLevel {
    /// Invalid stop level.
    ESTOP_LEVEL_UNKNOWN = 0;

    /// Immediately cut power to the actuators.
    ESTOP_LEVEL_CUT = 1;

    /// Prepare for loss of actuator power, then cut power.
    ESTOP_LEVEL_SETTLE_THEN_CUT = 2;

    ESTOP_LEVEL_CEASE = 3;

    /// No-stop level. The endpoint believes the robot is safe to operate.
    ESTOP_LEVEL_NONE = 4;
}

/// Configuration of a root / server.
message EstopConfig {
    /// EstopEndpoints that are part of this configuration.
    /// Unique IDs do not have to be filled out, but can be.
    repeated EstopEndpoint endpoints = 1;

    /// Unique ID for this configuration.
    string unique_id = 2;
}

/// EstopEndpoint with some extra status data.
message EstopEndpointWithStatus {
    /// The endpoint.
    EstopEndpoint endpoint = 1;

    /// Stop level most recently requested by the endpoint.
    EstopStopLevel stop_level = 2;

    /// Time since a valid response was provided by the endpoint.
    google.protobuf.Duration time_since_valid_response = 3;
}

/// Status of Estop system.
message EstopSystemStatus {
    /// Status for all available endpoints.
    repeated EstopEndpointWithStatus endpoints = 3;

    /// Current stop level for the system.
    /// Will be the most-restrictive stop level specified by an endpoint, or a stop level
    /// asserted by the system as a whole (e.g. if an endpoint timed out).
    EstopStopLevel stop_level = 4;

    /// Human-readable information on the stop level.
    string stop_level_details = 5;
}


/// Client request for setting/maintaining an estop system level.
/// After the first CheckIn, must include response to previous challenge.
message EstopCheckInRequest {
    /// Common request header.
    RequestHeader header = 1;

    /// The endpoint making the request.
    EstopEndpoint endpoint = 2;

    /// Challenge being responded to.
    /// Don't set if this is the first EstopCheckInRequest.
    uint64 challenge = 3;

    /// Response to above challenge.
    /// Don't set if this is the first EstopCheckInRequest.
    uint64 response = 4;

    /// Assert this stop level.
    EstopStopLevel stop_level = 5;
}

/// Server response to EstopCheckInRequest.
message EstopCheckInResponse {
    /// Common response header.
    ResponseHeader header = 1;

    /// Copy of initial request.
    EstopCheckInRequest request = 2;

    /// Next challenge to answer.
    uint64 challenge = 3;

    enum Status {
        /// Unknown error occurred.
        STATUS_UNKNOWN = 0;

        /// Valid challenge has been returned.
        STATUS_OK = 1;

        /// The endpoint specified in the request is not registered.
        STATUS_ENDPOINT_UNKNOWN = 2;


        /// The challenge and/or response was incorrect.
        STATUS_INCORRECT_CHALLENGE_RESPONSE = 5;
    }
    /// Status code for the response.
    Status status = 4;
}

/// Register an endpoint.
/// EstopEndpoints must be registered before they can send commands or request challenges.
message RegisterEstopEndpointRequest {
    /// Common request header
    RequestHeader header = 1;

    /// The endpoint to replace.
    /// Set the endpoint's unique ID if replacing an active endpoint.
    EstopEndpoint target_endpoint = 2;

    /// ID of the configuration we are registering against.
    string target_config_id = 3;

    /// The description of the new endpoint.
    /// Do not set the unique ID. It will be ignored.
    EstopEndpoint new_endpoint = 4;
}

/// Response to registration request.
message RegisterEstopEndpointResponse {
    /// Common response header
    ResponseHeader header = 1;

    /// Copy of the initial request.
    RegisterEstopEndpointRequest request = 2;

    /// The resulting endpoint on success.
    EstopEndpoint new_endpoint = 3;

    enum Status {
        /// An unknown / unexpected error occurred.
        STATUS_UNKNOWN = 0;

        /// Request succeeded.
        STATUS_SUCCESS = 1;

        /// Target endpoint did not match.
        STATUS_ENDPOINT_MISMATCH = 2;

        /// Registered to wrong configuration.
        STATUS_CONFIG_MISMATCH = 3;

        /// New endpoint was invalid.
        STATUS_INVALID_ENDPOINT = 4;
    }
    /// Status code for the response.
    Status status = 4;
}

/// Deregister the specified estop endpoint registration.
message DeregisterEstopEndpointRequest {
    /// Common request header
    RequestHeader header = 1;

    /// The endpoint to deregister.
    EstopEndpoint target_endpoint = 2;

    /// ID of the configuration we are registering against.
    string target_config_id = 3;
}

/// Response to estop endpoint  deregistration request.
message DeregisterEstopEndpointResponse {
    /// Common resonse header.
    ResponseHeader header = 1;

    /// Copy of the initial request.
    DeregisterEstopEndpointRequest request = 2;

    enum Status {
        /// An unknown / unexpected error occurred.
        STATUS_UNKNOWN = 0;

        /// Request succeeded.
        STATUS_SUCCESS = 1;

        /// Target endpoint did not match.
        STATUS_ENDPOINT_MISMATCH = 2;

        /// Registered to wrong configuration.
        STATUS_CONFIG_MISMATCH = 3;
    }
    /// Status code for the response.
    Status status = 4;
}

/// Get the active EstopConfig.
message GetEstopConfigRequest {
    /// Common request header.
    RequestHeader header = 1;

    /// unique_id of EstopConfig to get.
    string target_config_id = 4;
}

/// Response to EstopConfigRequest.
message GetEstopConfigResponse {
    /// Common response header.
    ResponseHeader header = 1;

    /// Copy of the request.
    GetEstopConfigRequest request = 2;

    /// The currently active configuration.
    EstopConfig active_config = 3;
}

/// Set a new active EstopConfig.
message SetEstopConfigRequest {
    /// Common request header.
    RequestHeader header = 1;

    /// New configuration to set.
    EstopConfig config = 3;

    /// unique_id of EstopConfig to replace, if replacing one.
    string target_config_id = 4;
}

/// Response to EstopConfigRequest.
message SetEstopConfigResponse {
    /// Common response header.
    ResponseHeader header = 1;

    /// Copy of the request.
    SetEstopConfigRequest request = 2;

    /// The currently active configuration.
    EstopConfig active_config = 3;

    enum Status {
        /// An unknown / unexpected error occurred.
        STATUS_UNKNOWN = 0;

        /// Request succeeded.
        STATUS_SUCCESS = 1;

        /// Tried to replace a EstopConfig, but provided bad ID.
        STATUS_INVALID_ID = 2;

    }
    Status status = 4;
}

/// Ask for the current status of the Estop system.
message GetEstopSystemStatusRequest {
    /// Common request header.
    RequestHeader header = 1;
}

/// Respond with the current Estop system status.
message GetEstopSystemStatusResponse {
    /// Common response header.
    ResponseHeader header = 1;

    /// Status of the Estop system.
    EstopSystemStatus status = 3;
}