@science-corporation/synapse 0.9.0

package/src/nodes/spike_detect.ts

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

package/src/nodes/stream_in.ts

@@ -0,0 +1,83 @@
+import dgram from "dgram";
+
+import { synapse } from "../api/api";
+import Node from "../node";
+
+export interface StreamInArgs {
+  dataType: synapse.DataType;
+  shape?: number[];
+}
+
+class StreamIn extends Node {
+  type = synapse.NodeType.kStreamIn;
+  config: synapse.IStreamInConfig;
+  _socket: dgram.Socket;
+
+  constructor(config: synapse.IStreamInConfig = {}) {
+    super();
+    this.config = config;
+  }
+
+  write(data: string | Buffer): boolean {
+    if (this.device === null) {
+      return false;
+    }
+
+    const socket = this.device.sockets.find((s) => s.nodeId === this.id);
+    if (!socket) {
+      return false;
+    }
+
+    const split = socket.bind.split(":");
+    if (split.length !== 2) {
+      return false;
+    }
+
+    const port = parseInt(split[1]);
+    if (isNaN(port)) {
+      return false;
+    }
+
+    const host = split[0];
+    if (!host || !port) {
+      return false;
+    }
+
+    if (!this._socket) {
+      this._socket = dgram.createSocket("udp4");
+    }
+
+    try {
+      this._socket.send(data, port, host);
+    } catch (e) {
+      return false;
+    }
+
+    return true;
+  }
+
+  toProto(): synapse.NodeConfig {
+    return super.toProto({
+      streamIn: this.config,
+    });
+  }
+
+  _getAddr = (): string | null => {
+    if (this.device === null) {
+      return null;
+    }
+
+    return this.device.uri.split(":")[0];
+  };
+
+  static fromProto(proto: synapse.INodeConfig): StreamIn {
+    const { streamIn } = proto;
+    if (!streamIn) {
+      throw new Error("Invalid config, missing streamIn");
+    }
+
+    return new StreamIn(streamIn);
+  }
+}
+
+export default StreamIn;

package/src/nodes/stream_out.ts

@@ -0,0 +1,92 @@
+import dgram from "dgram";
+
+import { synapse } from "../api/api";
+import Node from "../node";
+
+const kMulticastTTL = 3;
+
+class StreamOut extends Node {
+  type = synapse.NodeType.kStreamOut;
+  config: synapse.IStreamOutConfig;
+  _socket: dgram.Socket;
+  _onMessage: ((msg: Buffer) => void) | null;
+
+  constructor(config: synapse.IStreamOutConfig, onMessage?: (msg: Buffer) => void) {
+    super();
+
+    this.config = config;
+    this._onMessage = onMessage;
+  }
+
+  async start(): Promise<any> {
+    if (this.device === null) {
+      return false;
+    }
+
+    const socket = this.device.sockets.find((s) => s.nodeId === this.id);
+    if (!socket) {
+      return false;
+    }
+
+    const split = socket.bind.split(":");
+    if (split.length !== 2) {
+      return false;
+    }
+
+    const port = parseInt(split[1]);
+    if (isNaN(port)) {
+      return false;
+    }
+
+    const host = this.config.multicastGroup;
+    if (!host) {
+      return false;
+    }
+
+    this._socket = dgram.createSocket("udp4");
+
+    this._socket.on("error", (err: any) => {});
+
+    this._socket.on("message", (msg: Buffer, rinfo: any) => {
+      this._onMessage?.(msg);
+    });
+
+    this._socket.bind(port, host, () => {
+      if (!this._socket) {
+        return;
+      }
+
+      if (this.config.multicastGroup) {
+        this._socket.setMulticastTTL(kMulticastTTL);
+        this._socket.addMembership(this.config.multicastGroup);
+      }
+    });
+
+    return true;
+  }
+
+  async stop(): Promise<any> {
+    if (this._socket) {
+      this._socket.close();
+    }
+
+    return true;
+  }
+
+  toProto(): synapse.NodeConfig {
+    return super.toProto({
+      streamOut: this.config,
+    });
+  }
+
+  static fromProto(proto: synapse.INodeConfig): StreamOut {
+    const { streamOut } = proto;
+    if (!streamOut) {
+      throw new Error("Invalid config, missing streamOut");
+    }
+
+    return new StreamOut(streamOut);
+  }
+}
+
+export default StreamOut;

package/src/utils/client.ts

@@ -0,0 +1,20 @@
+import { ChannelCredentials, ChannelOptions, loadPackageDefinition } from "@grpc/grpc-js";
+import { fromJSON } from "@grpc/proto-loader";
+
+import protoJson from "../api/proto.json";
+
+const loadClient = () => {
+  const definition = fromJSON(protoJson as any, {
+    keepCase: false,
+    arrays: true,
+    enums: Number,
+    defaults: true,
+    oneofs: true,
+  });
+  const descriptor = loadPackageDefinition(definition as any);
+  return (descriptor.synapse as any).SynapseDevice;
+};
+
+export const create = (address: string, credentials: ChannelCredentials, options?: ChannelOptions) => {
+  return new (loadClient())(address, credentials, options);
+};

package/src/utils/discover.ts

@@ -0,0 +1,82 @@
+import dgram from "dgram";
+
+const kDefaultTimeout = 3000;
+
+interface DiscoverArgs {
+  host: string;
+  port: number;
+  timeoutMs?: number;
+}
+
+class DeviceAdvertisement {
+  host: string;
+  port: number;
+  serial: string;
+  capability: string;
+  name: string;
+}
+
+const kDefaultDiscoverArgs: DiscoverArgs = {
+  host: "224.0.0.245",
+  port: 6470,
+  timeoutMs: kDefaultTimeout,
+};
+
+export const discover = (args = kDefaultDiscoverArgs): Promise<DeviceAdvertisement[]> => {
+  return new Promise((resolve, reject) => {
+    const devices: DeviceAdvertisement[] = [];
+
+    const socket = dgram.createSocket("udp4");
+
+    socket.on("message", (msg: Buffer, rinfo: any) => {
+      const server = `${rinfo.address}:${rinfo.port}`;
+      const message = msg.toString("ascii");
+      const split = message.split(" ");
+
+      if (split.length < 5) {
+        return;
+      }
+
+      if (split[0] !== "ID") {
+        return;
+      }
+
+      const host = rinfo.address;
+      const [_, serial, capability, portstr, name] = split;
+      const port = parseInt(portstr);
+      if (isNaN(port)) {
+        return;
+      }
+
+      const service = capability.split(/(\d+)/)[0];
+      if (service !== "SYN") {
+        return;
+      }
+
+      devices.push({
+        host,
+        port,
+        serial,
+        capability,
+        name,
+      });
+    });
+
+    const payload = Buffer.from(`DISCOVER`, "ascii");
+
+    socket.send(payload, 0, payload.length, args.port, args.host, () => {
+      if (!args.timeoutMs) {
+        return;
+      }
+      setTimeout(() => socket.close(), kDefaultTimeout);
+    });
+
+    socket.on("error", (err: any) => {
+      reject(err);
+    });
+
+    socket.on("close", () => {
+      resolve(devices);
+    });
+  });
+};

package/src/utils/enum.ts

@@ -0,0 +1,8 @@
+export const getName = (enumType: any, value: number | string): string => {
+  for (const key in enumType) {
+    if (enumType[key] === value) {
+      return key;
+    }
+  }
+  return "";
+};

package/src/utils/index.ts

@@ -0,0 +1 @@
+import { discover } from "./discover";

package/synapse-api/README.md

@@ -0,0 +1,15 @@
+# Synapse API 1.0
+
+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).
+
+# Python Installation
+
+You can install the official [Synapse Python client library](https://github.com/sciencecorp/synapse-python) using:
+
+`pip install science-synapse`
+
+# Other Installation
+
+You can use these protobufs in any language supported by gRPC, but we highly encourage you to use one of our existing clients in Python, C++, or TS/Node because they wrap it and add additional utilities.

package/synapse-api/api/channel.proto

@@ -0,0 +1,9 @@
+syntax = "proto3";
+
+package synapse;
+
+message Channel {
+  uint32 id = 1;
+  uint32 electrode_id = 2;
+  uint32 reference_id = 3;
+}

package/synapse-api/api/datatype.proto

@@ -0,0 +1,12 @@
+syntax = "proto3";
+
+package synapse;
+
+enum DataType {
+    kDataTypeUnknown = 0;
+    kAny = 1;
+    kBroadband = 2;
+    kSpiketrain = 3;
+    kTimestamps = 4;
+    kImage = 5;
+}

package/synapse-api/api/files.proto

@@ -0,0 +1,46 @@
+syntax = "proto3";
+
+package synapse;
+
+import "api/status.proto";
+
+message ListFilesResponse {
+  message File {
+    string name = 1;
+    uint32 size = 2;
+    uint32 created = 3;
+    uint32 modified = 4;
+    string type = 5;
+  }
+  repeated File files = 1;
+}
+
+message WriteFileRequest {
+  string name = 1;
+  bytes data = 2;
+}
+
+message WriteFileResponse {
+  string name = 1;
+  uint64 bytes_written = 2;
+}
+
+message ReadFileRequest {
+  string name = 1;
+}
+
+message ReadFileResponse {
+  string name = 1;
+  bytes data = 2;
+  uint32 start_offset = 3;
+  uint32 file_total_length = 4;
+}
+
+message DeleteFileRequest {
+  string name = 1;
+}
+
+message DeleteFileResponse {
+  string name = 1;
+  StatusCode status_code = 2;
+}

package/synapse-api/api/node.proto

@@ -0,0 +1,54 @@
+syntax = "proto3";
+
+package synapse;
+
+import "api/datatype.proto";
+import "api/nodes/electrical_broadband.proto";
+import "api/nodes/electrical_stimulation.proto";
+import "api/nodes/optical_broadband.proto";
+import "api/nodes/optical_stimulation.proto";
+import "api/nodes/spike_detect.proto";
+import "api/nodes/spectral_filter.proto";
+import "api/nodes/stream_out.proto";
+import "api/nodes/stream_in.proto";
+
+enum NodeType {
+  kNodeTypeUnknown = 0;
+  kStreamIn = 1;
+  kStreamOut = 2;
+  kElectricalBroadband = 3;
+  kElectricalStimulation = 4;
+  kOpticalBroadband = 5;
+  kOpticalStimulation = 6;
+  kSpikeDetect = 7;
+  kSpectralFilter = 8;
+}
+
+message NodeConfig {
+  NodeType type = 1;
+  uint32 id = 2;
+  oneof config {
+    StreamOutConfig stream_out = 3;
+    StreamInConfig stream_in = 4;
+    ElectricalBroadbandConfig electrical_broadband = 5;
+    ElectricalStimulationConfig electrical_stimulation = 6;
+    OpticalBroadbandConfig optical_broadband = 7;
+    OpticalStimulationConfig optical_stimulation = 8;
+    SpikeDetectConfig spike_detect = 9;
+    SpectralFilterConfig spectral_filter = 10;
+  }
+}
+
+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/electrical_broadband.proto

@@ -0,0 +1,15 @@
+syntax = "proto3";
+
+import "api/channel.proto";
+
+package synapse;
+
+message ElectricalBroadbandConfig {
+  uint32 peripheral_id = 1;
+  repeated Channel channels = 2;
+  uint32 bit_width = 3;
+  uint32 sample_rate = 4;
+  float gain = 5;
+  float low_cutoff_hz = 6;
+  float high_cutoff_hz = 7;
+}

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

@@ -0,0 +1,13 @@
+syntax = "proto3";
+
+import "api/channel.proto";
+
+package synapse;
+
+message ElectricalStimulationConfig {
+  uint32 peripheral_id = 1;
+  repeated Channel channels = 2;
+  uint32 bit_width = 3;
+  uint32 sample_rate = 4;
+  uint32 lsb = 5;
+}

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

@@ -0,0 +1,11 @@
+syntax = "proto3";
+
+package synapse;
+
+message OpticalBroadbandConfig {
+  uint32 peripheral_id = 1;
+  repeated uint32 pixel_mask = 2;
+  uint32 bit_width = 3;
+  uint32 frame_rate = 4;
+  uint32 gain = 5;
+}

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

@@ -0,0 +1,11 @@
+syntax = "proto3";
+
+package synapse;
+
+message OpticalStimulationConfig {
+  uint32 peripheral_id = 1;
+  repeated uint32 pixel_mask = 2;
+  uint32 bit_width = 3;
+  uint32 frame_rate = 4;
+  float gain = 5;
+}

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

@@ -0,0 +1,17 @@
+syntax = "proto3";
+
+package synapse;
+
+enum SpectralFilterMethod {
+  kSpectralFilterUnknown = 0;
+  kLowPass = 1;
+  kHighPass = 2;
+  kBandPass = 3;
+  kBandStop = 4;
+}
+
+message SpectralFilterConfig {
+  SpectralFilterMethod method = 1;
+  float low_cutoff_hz = 2;
+  float high_cutoff_hz = 3;
+}

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

@@ -0,0 +1,16 @@
+syntax = "proto3";
+
+package synapse;
+
+message SpikeDetectConfig {
+  enum SpikeDetectMode {
+    kThreshold = 0;
+    kTemplate = 1;
+    kWavelet = 2;
+  }
+  SpikeDetectMode mode = 1;
+  uint32 threshold_uV = 2;
+  repeated uint32 template_uV = 3;
+  bool sort = 4;
+  uint32 bin_size_ms = 5;
+}

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

@@ -0,0 +1,9 @@
+syntax = "proto3";
+
+import "api/datatype.proto";
+
+package synapse;
+
+message StreamInConfig {
+  DataType data_type = 1;
+}

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

@@ -0,0 +1,8 @@
+syntax = "proto3";
+
+package synapse;
+
+message StreamOutConfig {
+  string label = 1;
+  string multicast_group = 2;
+}

package/synapse-api/api/query.proto

@@ -0,0 +1,46 @@
+syntax = "proto3";
+
+package synapse;
+
+import "api/channel.proto";
+import "api/status.proto";
+
+message SampleQuery {
+  repeated Channel channels = 1;
+  uint32 sample_count = 2;
+}
+
+message ImpedanceQuery {
+  repeated uint32 electrode_ids = 1;
+}
+
+message ImpedanceMeasurement {
+  uint32 electrode_id = 1;
+  float magnitude = 2;
+  float phase = 3;
+}
+
+message ImpedanceResponse {
+  repeated ImpedanceMeasurement measurements = 1;
+}
+
+message QueryRequest {
+  enum QueryType {
+    kNone = 0;
+    kImpedance = 1;
+    kSample = 2;
+  }
+  QueryType query_type = 1;
+  oneof query {
+    ImpedanceQuery impedance_query = 2;
+    SampleQuery sample_query = 3;
+  }
+}
+
+message QueryResponse {
+  Status status = 1;
+  repeated uint32 data = 2;
+  oneof response {
+    ImpedanceResponse impedance_response = 3;
+  }
+}

package/synapse-api/api/status.proto

@@ -0,0 +1,42 @@
+syntax = "proto3";
+
+package synapse;
+
+import "api/node.proto";
+
+enum StatusCode {
+  kOk = 0;
+  kUndefinedError = 1;
+  kInvalidConfiguration = 2;
+  kFailedPrecondition = 3;
+  kUnimplemented = 4;
+  kInternalError = 5;
+  kPermissionDenied = 6;
+}
+
+enum DeviceState {
+  kUnknown = 0;
+  kInitializing = 1;
+  kStopped = 2;
+  kRunning = 3;
+  kError = 4;
+}
+
+message DeviceStorage {
+  float total_gb = 1;
+  float used_gb = 2;
+}
+
+message DevicePower {
+  float battery_level_percent = 1;
+  bool is_charging = 2;
+}
+
+message Status {
+  string message = 1;
+  StatusCode code = 2;
+  DeviceState state = 3;
+  repeated NodeSocket sockets = 4;
+  DevicePower power = 5;
+  DeviceStorage storage = 6;
+}