github.com/binkynet/BinkyNet@v1.12.1-0.20240421190447-da4e34c20be0/apis/v1/types.proto

// Copyright 2019 Ewout Prangsma
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// 
// Author Ewout Prangsma
// 

syntax = "proto3";

package binkynet.v1;

import "github.com/gogo/protobuf/gogoproto/gogo.proto";

option go_package = "github.com/binkynet/BinkyNet/apis/v1";
option csharp_namespace = "BinkyNet.Apis.V1";

// Empty message
message Empty {}

// Information about the command station
message CommandStationInfo {
  // Unique identifier of the command station
  string id = 1;
  // Human readable description of the command station
  string description = 2;
  // Version of the command station in semantic versioning format.
  // E.g. 1.0.4
  string version = 3;
  // Uptime of the command station in seconds.
  int64 uptime = 4;
}

// Information about the local worker
message LocalWorkerInfo {
  // Unique identifier of the local worker
  string id = 1;
  // Human readable description of the local worker
  string description = 2;
  // Version of the local worker in semantic versioning format.
  // E.g. 1.0.4
  string version = 3;
  // Uptime of the local worker in seconds.
  int64 uptime = 4;
  // Hash of the current configuration
  string config_hash = 5;
  // IDs of all configured devices
  repeated string configured_device_ids = 6;
  // IDs of all configured objects
  repeated string configured_object_ids = 7;
  // IDs of all unconfigured devices
  repeated string unconfigured_device_ids = 8;
  // IDs of all unconfigured objects
  repeated string unconfigured_object_ids = 9;
  // HTTP(s) port to serve metrics on
  int32 metrics_port = 10;
  // If set to true, metrics are served over HTTPS, otherwise HTTP
  bool metrics_secure = 11;
  // Port this local worker is serving the LocalWorkerService on.
  int32 local_worker_service_port = 12;
  // If set, LocalWorkerService is served over TLS.
  bool local_worker_service_secure = 13;

  // If set, local worker implements LocalWorkerService.Reset
  bool supports_reset = 101;
  // If set, local worker implements LocalWorkerService.SetLocRequest
  bool supports_set_loc_request = 102;
  // If set, local worker implements LocalWorkerService.SetPowerRequest
  bool supports_set_power_request = 103;
  // If set, local worker implements LocalWorkerService.SetOutputRequest
  bool supports_set_output_request = 104;
  // If set, local worker implements LocalWorkerService.SetSwitchRequest
  bool supports_set_switch_request = 105;
  // If set, local worker implements LocalWorkerService.SetDeviceDiscoveryRequest
  bool supports_set_device_discovery_request = 106;
}

// Request arguments for GetPowerRequests
message PowerRequestsOptions {
  // If set, the network master must wait for an actual Power message
  // to confirm the state transition.
  // If not set, the network master assumes the power state is effective directly
  // after sending the message.
  bool manual_confirm = 1;
}

// Power message contains the requested & actual state of the power on the track.
message Power {
  // Requested power state 
  PowerState request = 1;
  // Actual power state
  PowerState actual = 2;
}

// PowerState message contains the requested/actual state of the power on the track.
message PowerState {
  // Power on/off
  bool enabled = 1;
}

// Request arguments for GetLocRequests
message LocRequestsOptions {
  // If set, the network master must wait for an actual Loc message
  // to confirm the state transition.
  // If not set, the network master assumes the state is effective directly
  // after sending the message.
  bool manual_confirm = 1;
}

// Direction of locs
enum LocDirection {
  FORWARD = 0;
  REVERSE = 1;
}

// Loc message is used to request/report the speed, direction & functions of a loc.
message Loc {
	// Addres of the loc
  string address = 1 [(gogoproto.customtype) = "ObjectAddress", (gogoproto.nullable) = false];
  // Requested state of the loc
  LocState request = 2;
  // Actual state of the loc
  LocState actual = 3;
}

// LocState message is used to request/report the speed, direction & functions of a loc.
message LocState {
	// Speed in steps
	int32 speed = 1;
	// Maximum speed steps of this loc
	int32 speed_steps = 2;
	// Direction "forward|reverse"
	LocDirection direction = 3;
	// State of functions
	map<int32, bool> functions = 4;
}

// Sensor captures the current value of a sensor with specified address
message Sensor {
	// Addres of the sensor
  string address = 1 [(gogoproto.customtype) = "ObjectAddress", (gogoproto.nullable) = false];
  // Current state of the sensor
  SensorState actual = 2;
}

// SensorState captures the current value of a sensor
message SensorState {
	// Current value of the sensor
	int32 value = 1;
}

// Request arguments for GetOutputRequests
message OutputRequestsOptions {
  // If set, the network master must wait for an actual Output message
  // to confirm the state transition.
  // If not set, the network master assumes the state is effective directly
  // after sending the message.
  bool manual_confirm = 1;
  // If set, pass only output requests that match this module ID.
  string module_id = 2;
}

// Output is used to control a generic output device. E.g. a light.
message Output {
	// Addres of the output
	string address = 1 [(gogoproto.customtype) = "ObjectAddress", (gogoproto.nullable) = false];
  // Requested state of the output
  OutputState request = 2;
  // Actual state of the output
  OutputState actual = 3;
}

// OutputState is used to request/report the state of a generic output device. E.g. a light.
message OutputState {
	// Value of the output
	int32 value = 1;
}

// Request arguments for GetSwitchRequests
message SwitchRequestsOptions {
  // If set, the network master must wait for an actual Output message
  // to confirm the state transition.
  // If not set, the network master assumes the state is effective directly
  // after sending the message.
  bool manual_confirm = 1;
  // If set, pass only switch requests that match this module ID.
  string module_id = 2;
}

// Direction of switches
enum SwitchDirection {
  STRAIGHT = 0;
  OFF = 1;
}

// Switch is used to request/report the state of a generic switch.
message Switch {
	// Addres of the switch
	string address = 1 [(gogoproto.customtype) = "ObjectAddress", (gogoproto.nullable) = false];
  // Requested state of the switch
  SwitchState request = 2;
  // Actual state of the switch
  SwitchState actual = 3;
}

// SwitchState describe the requested/actual state of a generic switch.
message SwitchState {
	// Requested/current direction of the switch
	SwitchDirection direction = 1;
  // Set if the switch is currently in use. 
  // This can be used to power down a switch if it is not in use.
  bool is_used = 2;
}

// TimePeriod indicates time of day in 4 periods.
enum TimePeriod {
  MORNING = 0;
  AFTERNOON = 1;
  EVENING = 2;
  NIGHT = 3;
}

// Clock is used to identity global time.
message Clock {
  // Current time period.
  TimePeriod period = 1;
  // Current hours (0..23)
  int32 hours = 2;
  // Current minutes (0..59)
  int32 minutes = 3;
  // Current realworld time in seconds elapsed since January 1, 1970 UTC
  int64 unixtime = 4;
}

// Device represents a hardware device such as a I2C chip.
message Device {
  // ID of the device
  string id = 1 [(gogoproto.customtype) = "DeviceID", (gogoproto.nullable) = false];
  // Type of the device.
  // See devicetypes.go
  string type = 2 [(gogoproto.customtype) = "DeviceType", (gogoproto.nullable) = false];
  // Logical address of the device on the local worker.
  string address = 3;
}

// Object represents a logical object on the railway such as a switch.
message Object {
  // ID of the object
  string id = 1 [(gogoproto.customtype) = "ObjectID", (gogoproto.nullable) = false];
  // Type of the object.
  // See objectypes.go
  string type = 2 [(gogoproto.customtype) = "ObjectType", (gogoproto.nullable) = false];
	// Connections to devices used by this object
	// The keys used in this map are specific to the type of object.
  repeated Connection connections = 3;
	// Optional configuration for this object.
	// Keys & values are specific to the object type.
	map<string, string> configuration = 4 [(gogoproto.castkey) = "ObjectConfigKey"];
}

// Connection from an Object to a Device.
message Connection {
  // Key is specific to the type of device.
  string key = 1 [(gogoproto.customtype) = "ConnectionName", (gogoproto.nullable) = false];
	// Pins of devices to connect to
	repeated DevicePin pins = 2;
	// Optional configuration for this connection.
	// Keys & values are specific to the connection name.
	map<string, string> configuration = 3 [(gogoproto.castkey) = "ConfigKey"];
}

// DevicePin identifies a hardware device and an index within that hardware address.
message DevicePin {
	// Unique identifier of the device that this connection refers to.
  string device_id = 1 [(gogoproto.customtype) = "DeviceID", (gogoproto.nullable) = false, (gogoproto.jsontag) = "device"];
  // Index on the device (1...)
  uint64 index = 2 [(gogoproto.customtype) = "DeviceIndex", (gogoproto.nullable) = false];
}

// Configuration for a local worker
message LocalWorkerConfig {
  // Human readable alias for this local worker.
  string alias = 1;
  // List of devices that must be configured on this local worker.
  repeated Device devices = 2;
	// List of real world objects controlled by the local worker
  repeated Object objects = 3;
  // Timestamp of network manager in seconds since 1970.
  int64 unixtime = 4;
  // Hash of the configuration (excluding unixtime)
  string hash = 5;
}

// Requested & actual state of a local worker
message LocalWorker {
  // Unique identifier of the local worker
  string id = 1;
  // Requested configuration of the local worker
  LocalWorkerConfig request = 2;
  // Actual state of the local worker 
  LocalWorkerInfo actual = 3;
}

// Request to discover devices on a local worker
message DeviceDiscovery {
  // ID of the module to perform the request on
  string id = 1;
  // Requested state of the discovery
  DiscoverRequest request = 2;
  // Actual state of the discovery
  DiscoverResult actual = 3;
}

// DiscoverRequest is sent when the netmanager wants to local worker to
// probe its locally attached devices.
message DiscoverRequest {
  // Unique ID of the request
  int32 request_id = 1;
}

// DiscoverResult is returned in a response to a discover request by the netmanager.
message DiscoverResult {
  // ID of local worker
  string id = 1;
  // The addresses that were found
  repeated string addresses = 2;
}