@science-corporation/synapse 2.0.0 → 2.2.2

package/README.md

@@ -79,3 +79,10 @@ config.connect(broadband, streamOut);
 await device.configure(config);
 await device.start();
 ```
+
+## Bumping Version
+```
+npm version patch # increment last part of version number
+npm version minor # increment middle part
+npm version major # increment first part
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@science-corporation/synapse",
-  "version": "2.0.0",
+  "version": "2.2.2",
   "description": "Client library and CLI for the Synapse API",
   "license": "Apache-2.0",
   "main": "dist/index.js",
@@ -63,7 +63,8 @@
     "@grpc/proto-loader": "^0.7.13",
     "google-protobuf": "^3.21.2",
     "long": "^5.3.1",
-    "protobufjs-cli": "^1.1.2",
+    "protobufjs-cli": "^1.1.3",
+    "tmp": "^0.2.5",
     "yargs": "^17.7.2"
   }
 }

package/src/config.ts

@@ -8,8 +8,6 @@ import SpectralFilter from "./nodes/spectral_filter";
 import SpikeBinner from "./nodes/spike_binner";
 import SpikeDetector from "./nodes/spike_detector";
 import SpikeSource from "./nodes/spike_source";
-import StreamIn from "./nodes/stream_in";
-import StreamOut from "./nodes/stream_out";
 import { Status, StatusCode } from "./utils/status";
 
 type Connection = [number, number];
@@ -21,9 +19,7 @@ const kNodeTypeObjectMap = {
   [synapse.NodeType.kOpticalStimulation]: OpticalStimulation,
   [synapse.NodeType.kSpectralFilter]: SpectralFilter,
   [synapse.NodeType.kSpikeBinner]: SpikeBinner,
-  [synapse.NodeType.kSpikeDetector]: SpikeDetector,
-  [synapse.NodeType.kStreamIn]: StreamIn,
-  [synapse.NodeType.kStreamOut]: StreamOut,
+  [synapse.NodeType.kSpikeDetector]: SpikeDetector
 };
 
 class Config {

package/src/device.ts

@@ -11,7 +11,6 @@ const kSynapseService = "synapse.SynapseDevice";
 class Device {
   rpc: any | null = null;
   channel: Channel | null = null;
-  sockets: synapse.INodeSocket[] = [];
 
   constructor(public uri: string) {
     const { status, client } = create(protos, kSynapseService)(uri, credentials.createInsecure());
@@ -48,8 +47,6 @@ class Device {
         } else if (!res) {
           reject(new Status(err.code, "failed to get device info: " + err.message));
         } else {
-          const { sockets } = res.status;
-          this.sockets = sockets || [];
           resolve({ status: new Status(), response: res });
         }
       });
@@ -168,11 +165,10 @@ class Device {
   }
 
   _handleStatusResponse(status: synapse.IStatus): Status {
-    const { code, message, sockets } = status;
+    const { code, message } = status;
     if (code !== synapse.StatusCode.kOk) {
       return fromDeviceStatus({ code, message });
     } else {
-      this.sockets = sockets || [];
       return new Status();
     }
   }

package/src/nodes/index.ts

@@ -6,7 +6,5 @@ export { default as SpectralFilter } from "./spectral_filter";
 export { default as SpikeBinner } from "./spike_binner";
 export { default as SpikeDetector } from "./spike_detector";
 export { default as SpikeSource } from "./spike_source";
-export { default as StreamIn } from "./stream_in";
-export { default as StreamOut } from "./stream_out";
 
 export type * from "../api/api";

package/synapse-api/README.md

@@ -2,7 +2,7 @@
 
 The Synapse Protocol defines a standard interface for interacting with a wide range of possible neural interface devices.
 
-Synapse uses gRPC for its control plane API and UDP for streaming data. Read the full Synapse protocol docs [here](https://science.xyz/docs/d/synapse/index).
+Synapse uses gRPC for its control plane API and Taps for streaming data. Read the full Synapse protocol docs [here](https://science.xyz/docs/d/synapse/index).
 
 # Python Installation
 

package/synapse-api/api/app.proto

@@ -0,0 +1,55 @@
+syntax = "proto3";
+
+package synapse;
+
+import "api/status.proto";
+import "api/performance.proto";
+import "api/device.proto";
+
+import "google/protobuf/struct.proto";
+
+message AppManifest {
+  // Your application name
+  string name = 1;
+
+  // JSON Schema for validating configuration
+  google.protobuf.Struct config_schema = 2;
+
+  // DeviceConfiguration describing the signal chain/device config
+  DeviceConfiguration device_config = 3;
+}
+
+message PackageMetadata {
+  // the package name
+  // e.g. synapse-example-app_0.1.0_arm64.deb
+  string name = 1;
+
+  // The version of the package to be uploaded
+  string version = 2;
+
+  // Package size, in bytes
+  uint64 size = 3;
+
+  // sha256 of the package, for verification
+  string sha256_sum = 4;
+}
+
+message AppPackageChunk {
+  // The first chunk is the metadata, with subsequent chunks being the file to install
+  oneof data {
+    PackageMetadata metadata = 1;
+    bytes file_chunk = 2;
+  }
+}
+
+message AppDeployResponse { 
+  StatusCode status = 1;
+
+  // Informational messages
+  string message = 2;
+}
+
+message AppPerformanceSummary {
+  uint64 timestamp_ns = 1;
+  repeated FunctionProfile function_profiles = 2;
+}

package/synapse-api/api/channel.proto

@@ -2,8 +2,22 @@ syntax = "proto3";
 
 package synapse;
 
+enum ChannelType {
+  ELECTRODE = 0;
+  GPIO = 1;
+}
+
 message Channel {
   uint32 id = 1;
   uint32 electrode_id = 2;
   uint32 reference_id = 3;
-}
+  ChannelType type = 4;
+}
+
+message ChannelRange {
+    ChannelType type = 1;
+    uint32 count = 2;
+    // Optional: for non-contiguous channels (e.g., GPIO), specifies which
+    //           channel ids are included, in order. Empty for contiguous
+    repeated uint32 channel_ids = 3;
+}

package/synapse-api/api/datatype.proto

@@ -2,6 +2,9 @@ syntax = "proto3";
 
 package synapse;
 
+import "google/protobuf/struct.proto";
+import "api/channel.proto";
+
 enum DataType {
     kDataTypeUnknown = 0;
     kAny = 1;
@@ -10,4 +13,97 @@ enum DataType {
     kTimestamps = 4;
     kImage = 5;
     kWaveforms = 6;
-}
+}
+
+// A simple tensor with timestamped data
+message Tensor {
+    // Timestamp in ns since the unix epoch
+    uint64 timestamp_ns = 1;
+    
+    // Shape of the tensor
+    // The number of values should equal to the product of the dimensions
+    // e.g. shape = [2, 3] => 2 rows, 3 columns
+    repeated int32 shape = 2;
+    
+    // Expected data type to parse out
+    enum DType {
+        DT_INVALID = 0;
+        DT_FLOAT = 1;
+        DT_DOUBLE = 2;
+        DT_UINT8 = 3;
+        DT_UINT16 = 4;
+        DT_UINT32 = 5;
+        DT_UINT64 = 6;
+        DT_INT8 = 7;
+        DT_INT16 = 8;
+        DT_INT32 = 9;
+        DT_INT64 = 10;
+        DT_BOOL = 11;
+    }
+    DType dtype = 3;
+
+    enum Endianness {
+        TENSOR_LITTLE_ENDIAN = 0;
+        TENSOR_BIG_ENDIAN = 1;
+    }
+    // We default to little because that covers most of the use cases
+    Endianness endianness = 4;
+
+    // Data, stored in a flat array, see shape to reconstruct
+    // e.g. shape: [1, 3] would be:
+    // [10.0, 20.0, 30.0]
+    bytes data = 5;
+}
+
+// A sample of all of the channels at a specific timepoint
+message BroadbandFrame {
+  // Monotonic timestamp when this frame was recorded based on the sampling rate
+  // At the start of a recording, the unix steady clock is recorded
+  // This timestamp is being calculated by
+  // start_timestamp_ns + (current_seq_num - start_seq_num) * 1e9 / sample_rate
+  uint64 timestamp_ns = 1;
+
+  // Monotonically increasing sequence number
+  // useful to detect missed or dropped frames
+  uint64 sequence_number = 2;
+
+  // The actual frame data, indexed by channel id
+  repeated sint32 frame_data = 3;
+
+  // Used for reconstructing multiple frames
+  uint32 sample_rate_hz = 4;
+
+  // When empty, all frame_data entries are electrode channels (legacy behavior).
+  // Describes contiguous ranges of channel types in frame_data, in order.
+  // Example:
+  // [{type: ELECTRODE}, count: 64, {type:GPIO, count:3, channel_ids:[0, 2, 5]}]
+  // This means frame_data[0..63] are electrodes, frame_data[64..66] are GPIO lines 0, 2, 5
+  repeated ChannelRange channel_ranges = 5;
+
+  // For legacy reasons, and syncing with other parts of the system, the current
+  // steady clock in unix time as reported by the system
+  // e.g. std::chrono::steady_clock::now().time_since_epoch()
+  uint64 unix_timestamp_ns = 6;
+}
+
+message Timeseries {
+  // An identifier for the channel of data from which the timeseries was recorded. 
+  uint32 id = 1;
+
+  // Represents a single sample of data at a specific timepoint
+  message Datapoint {
+    uint64 timestamp_ns = 1; // Timestamp of the recorded sample in ns since the unix epoch.
+    sint32 sample = 2; // The actual sample value.
+  }
+  repeated Datapoint datapoints = 2; // Collection of datapoints for this timeseries.
+}
+
+// A tensor with associated metadata
+message AnnotatedTensor {
+  // The tensor type
+  Tensor tensor = 1;
+  
+  // Generic metadata associated with the tensor
+  // e.g. pipeline latencies
+  map<string, google.protobuf.Value> metadata = 2;
+}

package/synapse-api/api/device.proto

@@ -0,0 +1,65 @@
+syntax = "proto3";
+
+package synapse;
+
+import "api/node.proto";
+import "api/status.proto";
+import "api/time.proto";
+
+message Peripheral {
+    enum Type {
+      kUnknown = 0;
+      kBroadbandSource = 1;
+      kElectricalStimulation = 2;
+      kOpticalStimulation = 3;
+      kSpikeSource = 4;
+    }
+    string name = 1;
+    string vendor = 2;
+    uint32 peripheral_id = 3;
+    Type type = 4;
+    string address = 5;
+}
+
+message DeviceInfo {
+    string name = 1;
+    string serial = 2;
+    uint32 synapse_version = 3;
+    uint32 firmware_version = 4;
+    Status status = 5;
+    repeated Peripheral peripherals = 6;
+    DeviceConfiguration configuration = 7;
+}
+
+message DeviceConfiguration {
+    repeated NodeConfig nodes = 1;
+    repeated NodeConnection connections = 2;
+}
+
+
+// Device settings that are configurable by the user
+message DeviceSettings {
+    string name = 1;
+    TimeSource time_source = 2;
+
+    // If configurable, the desired FPGA clock frequency in hz
+    uint32 fpga_clock_freq_hz = 3;
+}
+
+message GetSettingsQuery {
+
+}
+
+message GetSettingsResponse {
+    DeviceSettings settings = 1;
+}
+
+message UpdateDeviceSettingsRequest {
+    // If a field isn't populated, it will not be changed
+    DeviceSettings settings = 1;
+}
+
+message UpdateDeviceSettingsResponse {
+    Status status = 1;
+    DeviceSettings updated_settings = 2;
+}

package/synapse-api/api/node.proto

@@ -2,22 +2,22 @@ syntax = "proto3";
 
 package synapse;
 
-import "api/datatype.proto";
 import "api/nodes/broadband_source.proto";
 import "api/nodes/electrical_stimulation.proto";
 import "api/nodes/optical_stimulation.proto";
 import "api/nodes/spike_detector.proto";
 import "api/nodes/spectral_filter.proto";
-import "api/nodes/stream_out.proto";
-import "api/nodes/stream_in.proto";
 import "api/nodes/disk_writer.proto";
 import "api/nodes/spike_source.proto";
 import "api/nodes/spike_binner.proto";
+import "api/nodes/application.proto";
 
 enum NodeType {
   kNodeTypeUnknown = 0;
-  kStreamIn = 1;
-  kStreamOut = 2;
+  // kStreamIn = 1;
+  // kStreamOut = 2;
+  reserved 1, 2;
+
   kBroadbandSource = 3;
   kElectricalStimulation = 4;
   kOpticalStimulation = 5;
@@ -26,14 +26,18 @@ enum NodeType {
   kSpectralFilter = 8;
   kDiskWriter = 9;
   kSpikeBinner = 10;
+  kApplication = 11;
 }
 
 message NodeConfig {
   NodeType type = 1;
   uint32 id = 2;
+  
+  // StreamOutConfig stream_out = 3;
+  // StreamInConfig stream_in = 4;
+  reserved 3, 4;
+  
   oneof config {
-    StreamOutConfig stream_out = 3;
-    StreamInConfig stream_in = 4;
     BroadbandSourceConfig broadband_source = 5;
     ElectricalStimulationConfig electrical_stimulation = 6;
     OpticalStimulationConfig optical_stimulation = 8;
@@ -42,17 +46,23 @@ message NodeConfig {
     DiskWriterConfig disk_writer = 11;
     SpikeSourceConfig spike_source = 12;
     SpikeBinnerConfig spike_binner = 13;
+    ApplicationNodeConfig application = 14;
   }
 }
 
 message NodeStatus {
   NodeType type = 1;
   uint32 id = 2;
+
+  // StreamOutStatus stream_out = 3;
+  // StreamInStatus stream_in = 5;
+  reserved 3, 5;
   oneof status {
-    StreamOutStatus stream_out = 3;
     BroadbandSourceStatus broadband_source = 4;
-    StreamInStatus stream_in = 5;
     ElectricalStimulationStatus electrical_stimulation = 6;
+    ApplicationNodeStatus application = 7;
+    OpticalStimulationStatus optical_stimulation = 8;
+    DiskWriterStatus disk_writer = 10;
   }
 }
 
@@ -60,12 +70,3 @@ message NodeConnection {
   uint32 src_node_id = 1;
   uint32 dst_node_id = 2;
 }
-
-message NodeSocket {
-  uint32 node_id = 1;
-  string bind = 2;
-  DataType data_type = 3;
-  NodeType type = 4;
-  string label = 5;
-  repeated uint32 shape = 6;
-}

package/synapse-api/api/nodes/application.proto

@@ -0,0 +1,24 @@
+syntax = "proto3";
+
+package synapse;
+
+import "google/protobuf/struct.proto";
+
+message ApplicationNodeConfig {
+    // Your application name, it should match what is deployed
+    string name = 1;
+
+    // Application specific configuration, will be loaded by
+    // the custom application during runtime
+    map<string, google.protobuf.Value> parameters = 2;
+}
+
+message ApplicationNodeStatus {
+    string name = 1;
+
+    // Is the application started and running?
+    bool running = 2;
+
+    // If the application failed to start, what were the logs
+    string error_logs = 3;
+}

package/synapse-api/api/nodes/broadband_source.proto

@@ -18,3 +18,4 @@ message BroadbandSourceConfig {
 message BroadbandSourceStatus {
     SignalStatus status = 1;
 }
+

package/synapse-api/api/nodes/disk_writer.proto

@@ -5,3 +5,20 @@ package synapse;
 message DiskWriterConfig {
   string filename = 1;
 }
+
+message DiskWriterStatus {
+  // The output path of the file on the path of the sftp directory
+  string output_path = 1;
+
+  // How many bytes has been written for this file?
+  uint64 bytes_written = 2;
+
+  // Are we currently writing or are we stopped?
+  bool is_writing = 3;
+
+  // How many bytes are available for us to use
+  uint64 available_disk_space_bytes = 4;
+
+  // Current write performance for this node, megabits/sec
+  float current_bitrate_mbps = 5;
+}

package/synapse-api/api/nodes/optical_stimulation.proto

@@ -8,4 +8,33 @@ message OpticalStimulationConfig {
   uint32 bit_width = 3;
   uint32 frame_rate = 4;
   float gain = 5;
+
+  // Instruct the FPGA to send out a 1xN vector 
+  // where N is the number of LEDs with each Axon frame
+  bool send_receipts = 6;
+}
+
+// Core frame type for LED array optical stimulation
+message OpticalStimFrame {
+  uint64 frame_id = 1;
+  uint64 sequence_number = 2;
+  uint64 timestamp_ns = 3;
+
+  // Frame dimensions
+  uint32 rows = 4;
+  uint32 columns = 5;
+
+  // Normalized pixel intensities (0.0 - 1.0)
+  // Row major ordering
+  // 0.0 is completely off, 1.0 is completely on
+  repeated float intensity = 6;
+
+  // For passive displays, this represents the row on time
+  // For active, this represents frame on time
+  uint64 duration_us = 7;
+}
+
+message OpticalStimulationStatus {
+  // How many frames have we written?
+  uint64 frames_written = 1;
 }

package/synapse-api/api/nodes/signal_config.proto

@@ -6,6 +6,8 @@ package synapse;
 
 message ElectrodeConfig {
     repeated Channel channels = 1;
+
+    // Analog filter settings for electrode channels
     float low_cutoff_hz = 2;
     float high_cutoff_hz = 3;
 }

package/synapse-api/api/performance.proto

@@ -0,0 +1,29 @@
+syntax = "proto3";
+
+package synapse;
+
+// Statistics about the performance of a function call or block of computation
+message FunctionProfile {
+    string name = 1;
+
+    // How often has this been called
+    uint64 call_count = 2;
+
+    // What was the minimal time it took for this function to execute
+    uint64 min_duration_ns = 3;
+
+    // Maximum execution for this function
+    uint64 max_duration_ns = 4;
+
+    // Average (mean) of this function over all samples
+    uint64 average_duration_ns = 5;
+
+    // Median execution time over all samples
+    uint64 median_duration_ns = 6;
+
+    // p99 duration
+    uint64 p99_duration_ns = 7;
+
+    // The last measurement duration
+    uint64 latest_duration_ns = 8;
+}

package/synapse-api/api/query.proto

@@ -4,6 +4,8 @@ package synapse;
 
 import "api/channel.proto";
 import "api/status.proto";
+import "api/tap.proto";
+import "api/device.proto";
 
 message SampleQuery {
   repeated Channel channels = 1;
@@ -46,12 +48,16 @@ message QueryRequest {
     kImpedance = 1;
     kSample = 2;
     kSelfTest = 3;
+    kListTaps = 4;
+    kGetSettings = 5;
   }
   QueryType query_type = 1;
   oneof query {
     ImpedanceQuery impedance_query = 2;
     SampleQuery sample_query = 3;
     SelfTestQuery self_test_query = 4;
+    ListTapsQuery list_taps_query = 5;
+    GetSettingsQuery get_settings_query = 6;
   }
 }
 
@@ -67,6 +73,8 @@ message QueryResponse {
   oneof response {
     ImpedanceResponse impedance_response = 3;
     SelfTestResponse self_test_response = 4;
+    ListTapsResponse list_taps_response = 5;
+    GetSettingsResponse get_settings_response = 6;
   }
 }
 

package/synapse-api/api/status.proto

@@ -41,8 +41,13 @@ message Status {
   string message = 1;
   StatusCode code = 2;
   DeviceState state = 3;
-  repeated NodeSocket sockets = 4;
+  // repeated NodeSocket sockets = 4;
+  reserved 4;
   DevicePower power = 5;
   DeviceStorage storage = 6;
   SignalChainStatus signal_chain = 7;
+
+  // If the device supports a time sync server (see time.proto)
+  // Then the UDP echo server will be available at this port
+  uint32 time_sync_port = 8; // Port number (0-65535) for the UDP time sync server
 }

package/synapse-api/api/synapse.proto

@@ -3,41 +3,13 @@ syntax = "proto3";
 package synapse;
 
 import "google/protobuf/empty.proto";
-import "api/node.proto";
+
 import "api/query.proto";
 import "api/status.proto";
 import "api/files.proto";
 import "api/logging.proto";
-
-message Peripheral {
-  enum Type {
-    kUnknown = 0;
-    kBroadbandSource = 1;
-    kElectricalStimulation = 2;
-    kOpticalStimulation = 3;
-    kSpikeSource = 4;
-  }
-  string name = 1;
-  string vendor = 2;
-  uint32 peripheral_id = 3;
-  Type type = 4;
-  string address = 5;
-}
-
-message DeviceInfo {
-  string name = 1;
-  string serial = 2;
-  uint32 synapse_version = 3;
-  uint32 firmware_version = 4;
-  Status status = 5;
-  repeated Peripheral peripherals = 6;
-  DeviceConfiguration configuration = 7;
-}
-
-message DeviceConfiguration {
-  repeated NodeConfig nodes = 1;
-  repeated NodeConnection connections = 2;
-}
+import "api/app.proto";
+import "api/device.proto";
 
 service SynapseDevice {
   rpc Info(google.protobuf.Empty) returns (DeviceInfo) {}
@@ -47,10 +19,15 @@ service SynapseDevice {
   rpc Query(QueryRequest) returns (QueryResponse) {}
   rpc StreamQuery(StreamQueryRequest) returns (stream StreamQueryResponse) {}
 
+  rpc DeployApp(stream AppPackageChunk) returns (stream AppDeployResponse) {}
+
   rpc ListFiles(google.protobuf.Empty) returns (ListFilesResponse) {}
   rpc WriteFile(WriteFileRequest) returns (WriteFileResponse) {}
   rpc ReadFile(ReadFileRequest) returns (stream ReadFileResponse) {}
   rpc DeleteFile(DeleteFileRequest) returns (DeleteFileResponse) {}
+
   rpc GetLogs(LogQueryRequest) returns (LogQueryResponse) {}
   rpc TailLogs(TailLogsRequest) returns (stream LogEntry) {}
+
+  rpc UpdateDeviceSettings(UpdateDeviceSettingsRequest) returns (UpdateDeviceSettingsResponse) {}
 }