@science-corporation/synapse 1.1.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": "1.1.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

@@ -5,10 +5,9 @@ import DiskWriter from "./nodes/disk_writer";
 import ElectricalStimulation from "./nodes/electrical_stimulation";
 import OpticalStimulation from "./nodes/optical_stimulation";
 import SpectralFilter from "./nodes/spectral_filter";
-import SpikeDetect from "./nodes/spike_detect";
+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];
@@ -19,9 +18,8 @@ const kNodeTypeObjectMap = {
   [synapse.NodeType.kSpikeSource]: SpikeSource,
   [synapse.NodeType.kOpticalStimulation]: OpticalStimulation,
   [synapse.NodeType.kSpectralFilter]: SpectralFilter,
-  [synapse.NodeType.kSpikeDetect]: SpikeDetect,
-  [synapse.NodeType.kStreamIn]: StreamIn,
-  [synapse.NodeType.kStreamOut]: StreamOut,
+  [synapse.NodeType.kSpikeBinner]: SpikeBinner,
+  [synapse.NodeType.kSpikeDetector]: SpikeDetector
 };
 
 class Config {

package/src/device.ts

@@ -11,14 +11,13 @@ 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());
     if (!status.ok() || !client) {
       throw new Error(`Failed to create client for ${uri}: ${status.message}`);
     }
-    this.rpc = client;
+    this.rpc = client as synapse.SynapseDevice;
   }
 
   async configure(config: Config, options: CallOptions = {}): Promise<Status> {
@@ -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 });
         }
       });
@@ -90,6 +87,39 @@ class Device {
     });
   }
 
+  async streamQuery(
+    query: synapse.IStreamQueryRequest,
+    options: CallOptions = {},
+    callbacks: {
+      onData: (data: synapse.StreamQueryResponse) => void;
+      onEnd?: () => void;
+      onError?: (err: Error) => void;
+      onStatus?: (status: Status) => void;
+    }
+  ) {
+    const { onData, onEnd, onError, onStatus } = callbacks;
+    const call = this.rpc.streamQuery(query, options);
+    call.on("data", (data: synapse.StreamQueryResponse) => {
+      onData(data);
+    });
+    if (onEnd) {
+      call.on("end", () => {
+        onEnd();
+      });
+    }
+    if (onError) {
+      call.on("error", (err: ServiceError) => {
+        onError(err);
+      });
+    }
+    if (onStatus) {
+      call.on("status", (grpcStatus) => {
+        onStatus?.(new Status(grpcStatus.code, grpcStatus.details));
+      });
+    }
+    return call;
+  }
+
   // Logs
 
   async getLogs(
@@ -135,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

@@ -3,9 +3,8 @@ export { default as DiskWriter } from "./disk_writer";
 export { default as ElectricalStimulation } from "./electrical_stimulation";
 export { default as OpticalStimulation } from "./optical_stimulation";
 export { default as SpectralFilter } from "./spectral_filter";
-export { default as SpikeDetect } from "./spike_detect";
+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/src/nodes/spike_binner.ts

@@ -0,0 +1,30 @@
+import { synapse } from "../api/api";
+import Node from "../node";
+
+class SpikeBinner extends Node {
+  type = synapse.NodeType.kSpikeBinner;
+  config: synapse.ISpikeBinnerConfig;
+
+  constructor(config: synapse.ISpikeBinnerConfig = {}) {
+    super();
+
+    this.config = config;
+  }
+
+  toProto(): synapse.NodeConfig {
+    return super.toProto({
+      spikeBinner: this.config,
+    });
+  }
+
+  static fromProto(proto: synapse.INodeConfig): SpikeBinner {
+    const { spikeBinner } = proto;
+    if (!spikeBinner) {
+      throw new Error("Invalid config, missing spikeBinner");
+    }
+
+    return new SpikeBinner(proto.spikeBinner);
+  }
+}
+
+export default SpikeBinner;

package/src/nodes/spike_detector.ts

@@ -0,0 +1,30 @@
+import { synapse } from "../api/api";
+import Node from "../node";
+
+class SpikeDetector extends Node {
+  type = synapse.NodeType.kSpikeDetector;
+  config: synapse.ISpikeDetectorConfig;
+
+  constructor(config: synapse.ISpikeDetectorConfig = {}) {
+    super();
+
+    this.config = config;
+  }
+
+  toProto(): synapse.NodeConfig {
+    return super.toProto({
+      spikeDetector: this.config,
+    });
+  }
+
+  static fromProto(proto: synapse.INodeConfig): SpikeDetector {
+    const { spikeDetector } = proto;
+    if (!spikeDetector) {
+      throw new Error("Invalid config, missing spikeDetector");
+    }
+
+    return new SpikeDetector(proto.spikeDetector);
+  }
+}
+
+export default SpikeDetector;

package/synapse-api/.github/pull_request_template.md

@@ -0,0 +1,10 @@
+# Summary
+Brief overview of the changes
+
+# Changes
+* Detailed breakdown of what changed and why. If there are new/changed API concepts, explain how they are meant to be used.
+
+# Testing
+How can this change be tested?
+
+Please provide a link to a reference server and client implementation in synapse-python.

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;
@@ -9,4 +12,98 @@ enum DataType {
     kSpiketrain = 3;
     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,54 +2,67 @@ 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_detect.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;
-  kSpikeDetect = 6;
+  kSpikeDetector = 6;
   kSpikeSource = 7;
   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;
-    SpikeDetectConfig spike_detect = 9;
+    SpikeDetectorConfig spike_detector = 9;
     SpectralFilterConfig spectral_filter = 10;
     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;
   }
 }
 
@@ -57,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/nodes/spike_binner.proto

@@ -0,0 +1,7 @@
+syntax = "proto3";
+
+package synapse;
+
+message SpikeBinnerConfig {
+  uint32 bin_size_ms = 1;
+}