instinct-py 1.5.0

Python SDK for controlling and interacting with Nexstem Instinct Devices

Instinct SDK for Python

Python SDK for controlling and interacting with Nexstem Instinct devices.

Overview

The Instinct Python SDK provides a comprehensive set of tools for discovering, connecting to, and controlling Nexstem Instinct devices from Python applications. This SDK enables developers to:

• Discover Instinct devices on the local network
• Monitor device state (battery, CPU, RAM, storage)
• Configure electrodes and sensors
• Create and manage data streams
• Build custom signal processing pipelines
• Store and retrieve device configuration values

Installation

# Using pip
pip install instinct-sdk

# Using poetry
poetry add instinct-sdk

Requirements

• Python 3.9 or later
• An Instinct device on the same network

Quick Start

Discovering Instinct devices

from instinct_py import InstinctDevice

# Discover all Instinct devices on the network
devices = InstinctDevice.discover()
print(f"Found {len(devices)} Instinct devices")

# Connect to the first device found
device = devices[0]

# Or connect directly to a known device
device = InstinctDevice("192.168.1.100")

Getting Device State

# Get basic device information
state = device.get_state()
print(f"Device status: {state.status}")
print(f"Battery: {state.battery.percent}%")
print(f"CPU load: {state.cpu.load}%")

# Get the device name
name = device.get_name()
print(f"Device name: {name}")

Working with Streams

import uuid

source_id = str(uuid.uuid4())
ssvep_id = str(uuid.uuid4())

# Create a stream
stream = device.streams_manager.create_stream({
    "id": str(uuid.uuid4()),
    "nodes": [
        {
            "executable": "eeg_source",
            "config": {
                "sampleRate": 1000,
                "gain": 1,
            },
            "id": source_id,
        },
        {
            "executable": "ssvep_algo",
            "config": {},
            "id": ssvep_id,
        },
    ],
    "pipes": [
        {
            "source": source_id,
            "destination": ssvep_id,
        },
    ],
})

# Create the stream on the device
await stream.create()

# Start the stream
await stream.start()

# Stop the stream when done
await stream.stop()

API Documentation

InstinctDevice Class

The main entry point for interacting with Instinct devices.

Static Methods

Method	Description
InstinctDevice.discover(timeout=3000, discovery_port=48010, debug=False)	Discovers Instinct devices on the network

Instance Properties

Property	Type	Description
streams_manager	DeviceStreamsManager	Manager for creating and controlling data streams
electrode_manager	DeviceElectrodesManager	Manager for electrode configurations
sensor_manager	DeviceSensorsManager	Manager for sensor data
device_config_manager	DeviceConfigManager	Manager for device configuration storage
host_address	str	IP address of the Instinct Device

Instance Methods

Method	Description
get_state()	Gets the current state of the device
get_name()	Gets the current name of the device
set_name(name)	Sets a new name for the device
send_debug_command(command)	Sends a debug command to the device (debug mode only)

Device Configuration Management

The SDK provides DeviceConfigManager for storing and retrieving persistent configuration values on the device.

# Store user preferences
await device.device_config_manager.create_config({
    "key": "userPreference.theme",
    "value": "dark",
})

# Store temporary data with expiration
await device.device_config_manager.create_config({
    "key": "session.authToken",
    "value": "abc123xyz",
    "expires_in": "1h",
})

# Retrieve configuration
config = await device.device_config_manager.get_config("userPreference.theme")
print(f"Theme preference: {config.value}")

# Update configuration
await device.device_config_manager.update_config(
    "userPreference.theme",
    {
        "key": "userPreference.theme",
        "value": "light",
    }
)

# Delete configuration
await device.device_config_manager.delete_config("session.authToken")

Stream Management

The SDK provides classes for creating and managing data processing streams:

import uuid

# Create a stream with custom metadata
stream = device.streams_manager.create_stream({
    "meta": {
        "name": "Alpha Rhythm Analysis",
        "description": "Extracts and analyzes alpha rhythms from occipital electrodes",
        "version": "1.0.0",
    },
    "nodes": [
        {
            "executable": "eeg_source",
            "config": {
                "sampleRate": 250,
                "channels": ["O1", "O2", "PZ"],
            },
        },
        {
            "executable": "bandpass_filter",
            "config": {
                "cutoff": 10,
                "bandwidth": 4,
                "order": 4,
            },
        },
    ],
    "pipes": [
        {
            "source": "source_id",
            "destination": "destination_id",
        },
    ],
})

# Create and start the stream
await stream.create()
await stream.start()

# Stop and delete the stream when done
await stream.stop()
await stream.delete()

Electrode and Sensor Management

# List all electrodes
electrodes = await device.electrode_manager.list_electrodes()
for electrode in electrodes:
    print(f"{electrode.position}: {'enabled' if electrode.enabled else 'disabled'}")

# Enable an electrode
await device.electrode_manager.enable_electrode("PZ")

# List all sensors
sensors = await device.sensor_manager.list_sensors()
for sensor in sensors:
    print(f"{sensor.type}: {'enabled' if sensor.enabled else 'disabled'}")

# Enable the accelerometer
await device.sensor_manager.enable_sensor("accelerometer", sample_rate=100)

Error Handling

The SDK uses standard exception handling:

try:
    devices = InstinctDevice.discover()
    if len(devices) == 0:
        print("No Instinct Devices found.")
        exit()

    device = devices[0]
    await device.set_name("My Instinct Device")
except Exception as error:
    print(f"Error: {error}")

Troubleshooting

Common Issues

1. Cannot discover Instinct devices

   • Ensure that your Instinct device is powered on and connected to the same network
   • Check firewall settings that might block UDP broadcasts (port 48010)
   • Try specifying the IP address directly: InstinctDevice("192.168.1.100")

2. Stream creation fails

   • Verify all UUIDs are valid
   • Check that node executables exist on the device
   • Ensure pipe connections reference valid node IDs

3. Configuration storage fails

   • Check that the key is a valid string
   • Ensure the value can be properly serialized
   • Verify that the expiration format is correct (e.g., "1h", "2d", "30m")

4. Connection timeouts

   • The device may be overloaded; try simplifying your stream
   • Check network stability and latency
   • Increase timeout values in API calls

Resources

• Nexstem Developer Documentation
• Custom Nodes Tutorial
• API Reference