Common Workflows

This guide presents typical workflows and usage patterns for the Instinct API. These examples will help you understand how to combine various API endpoints to accomplish common tasks.

Data Processing Workflows

Creating and Running a Data Processing Pipeline

A common workflow is to create a data processing pipeline, start it, and monitor its execution:

1. Create a new stream:

   curl -X POST http://localhost:42069/stream/streams \
     -H "Content-Type: application/json" \
     -d '{
       "id": "cdc566b5-0221-4018-a99f-23265af1e04d",
       "meta": {
           "name": "Streams - Realtime stream - cdc566b5-0221-4018-a99f-23265af1e04d"
       },
       "nodes": [
           {
               "id": "94f92dc4-5a84-45c7-8543-9c18ba4df95c",
               "type": "EXECUTABLE",
               "meta": {
                   "type": "SOURCE"
               },
               "executable": "node /usr/share/engines/worker-scripts/SignalGenerator.js",
               "config": {
                   "sampleRate": 1000,
                   "amplitudes": [1, 2, 3, 4, 5, 6, 7, 8, 9],
                   "frequencies": [2, 3, 5, 6, 11, 23, 30, 50, 75]
               }
           },
           {
               "id": "a297523e-ab4b-41d9-b29c-c434eb4c9723",
               "type": "EXECUTABLE",
               "meta": {
                   "type": "OUTPUT"
               },
               "executable": "node /usr/share/engines/worker-scripts/WebSocket.js",
               "config": {
                   "port": 36006
               }
           }
       ],
       "pipes": [
           {
               "id": "50198da6-2426-4276-9ba4-d30f396f3d54",
               "source": "94f92dc4-5a84-45c7-8543-9c18ba4df95c",
               "destination": "a297523e-ab4b-41d9-b29c-c434eb4c9723"
           }
       ]
   }'

   Response:

   {
     "id": "cdc566b5-0221-4018-a99f-23265af1e04d",
     "success": true
   }

2. Start the stream:

   curl -X POST http://localhost:42069/stream/streams/cdc566b5-0221-4018-a99f-23265af1e04d/signal \
     -d "signal=start"

   Response:

   {
     "id": "cdc566b5-0221-4018-a99f-23265af1e04d",
     "success": true
   }

3. Stop the stream when done:

   curl -X POST http://localhost:42069/stream/streams/cdc566b5-0221-4018-a99f-23265af1e04d/signal \
     -d "signal=stop"

   Response:

   {
     "id": "cdc566b5-0221-4018-a99f-23265af1e04d",
     "success": true
   }

Dynamic Pipeline Modification

Another common workflow is modifying a pipeline while it's running:

1. Create and start the stream (as above)

2. Add a new node to the running stream:

   curl -X POST http://localhost:42069/stream/streams/cdc566b5-0221-4018-a99f-23265af1e04d/nodes \
     -H "Content-Type: application/json" \
     -d '[
       {
         "id": "64cb7ca2-ebca-4502-8fc4-208fa90545f4",
         "type": "EXECUTABLE_CONSUMER",
         "executable": "node /usr/share/engines/worker-scripts/Logger.js"
       }
     ]'

   Response:

   {
     "id": "cdc566b5-0221-4018-a99f-23265af1e04d",
     "success": true,
     "nodes": ["64cb7ca2-ebca-4502-8fc4-208fa90545f4"]
   }

3. Add pipes to connect the new node:

   curl -X POST http://localhost:42069/stream/streams/cdc566b5-0221-4018-a99f-23265af1e04d/pipes/yaml \
     -H "Content-Type: text/yaml" \
     --data-binary @- << EOF
   ---
   - id: 67a7a083-28b0-4dd5-b33d-e60e339bb93z
     source: 94f92dc4-5a84-45c7-8543-9c18ba4df95c
     destination: 64cb7ca2-ebca-4502-8fc4-208fa90545f4
   EOF

   Response:

   {
     "id": "cdc566b5-0221-4018-a99f-23265af1e04d",
     "pipes": ["67a7a083-28b0-4dd5-b33d-e60e339bb93z"],
     "success": true
   }

4. Remove nodes that are no longer needed:

   curl -X DELETE http://localhost:42069/stream/streams/cdc566b5-0221-4018-a99f-23265af1e04d/nodes \
     -H "Content-Type: application/json" \
     -d '["64cb7ca2-ebca-4502-8fc4-208fa90545f4"]'

   Response:

   {
     "id": "cdc566b5-0221-4018-a99f-23265af1e04d",
     "success": true,
     "nodes": ["64cb7ca2-ebca-4502-8fc4-208fa90545f4"]
   }

EEG Data Acquisition Workflows

EEG Streaming Workflow

A typical workflow for EEG streaming:

1. Configure EEG:

   curl -X POST http://localhost:42069/system/peripheral/electrodes/config \
     -H "Content-Type: application/json" \
     -d '{
       "samplingRate": 500,
       "gain": 24,
       "enabled": [0, 1, 2, 3, 4, 5, 6, 7],
       "inputType": "normal",
       "bias": true
     }'

   Response:

   {
     "success": true,
     "message": "Electrode config set successfully."
   }

2. Check electrode impedances (to ensure good contact):

   curl -X POST http://localhost:42069/system/peripheral/electrodes/impedance

   Response:

   {
     "success": true,
     "electrodes": [
       {
         "index": 0,
         "magnitude": 1152.921,
         "phase": 43.65823
       },
       {
         "index": 1,
         "magnitude": 1236.423,
         "phase": 39.56453
       }
       // Additional electrodes...
     ]
   }

3. Start EEG streaming:

   curl -X POST http://localhost:42069/system/peripheral/electrodes/stream

   Response:

   {
     "success": true,
     "message": "EEG streaming started."
   }

4. Stop EEG streaming when session completed:

   curl -X POST http://localhost:42069/system/peripheral/electrodes/stop

   Response:

   {
     "success": true,
     "message": "EEG streaming stopped"
   }

Hardware Control Workflows

Headset Configuration

Common headset configuration commands:

1. Check LED status:

   curl -X GET http://localhost:42069/system/peripheral/leds

   Response:

   {
     "success": true,
     "leds": [
       {
         "id": 0,
         "state": {
           "on": true,
           "color": "#00FF00",
           "blinkRate": 0
         }
       },
       {
         "id": 1,
         "state": {
           "on": false,
           "color": "#000000",
           "blinkRate": 0
         }
       }
     ]
   }

2. Set LED color and blink rate:

   curl -X PUT http://localhost:42069/system/peripheral/leds/0 \
     -H "Content-Type: application/json" \
     -d '{
       "on": true,
       "color": "#0000FF",
       "blinkRate": 2
     }'

   Response:

   {
     "success": true,
     "message": "LED state updated successfully."
   }

3. Check motor position:

   curl -X GET http://localhost:42069/system/peripheral/motors

   Response:

   {
     "success": true,
     "motors": [
       {
         "id": 0,
         "position": 90,
         "state": "idle"
       },
       {
         "id": 1,
         "position": 45,
         "state": "idle"
       }
     ]
   }

4. Move motors to position:

   curl -X POST http://localhost:42069/system/peripheral/motors/move \
     -H "Content-Type: application/json" \
     -d '{
       "motors": [
         {
           "id": 0,
           "position": 180
         },
         {
           "id": 1,
           "position": 90
         }
       ]
     }'

   Response:

   {
     "success": true,
     "message": "Motors movement started"
   }

5. Check battery status:

   curl -X GET http://localhost:42069/system/battery

   Response:

   {
     "success": true,
     "level": 85,
     "charging": false,
     "timeRemaining": "4h 30m",
     "temperature": 32.5,
     "health": "good"
   }

Integrated Workflows

Data Processing with Visualization

A complete workflow that combines data acquisition with real-time visualization:

1. Create a stream with multiple nodes (signal generator, data processor, and visualizer):

   curl -X POST http://localhost:42069/stream/streams \
     -H "Content-Type: application/json" \
     -d '{
       "id": "cdc566b5-0221-4018-a99f-23265af1e04d",
       "meta": {
         "name": "Realtime Processing Stream"
       },
       "nodes": [
         {
           "id": "94f92dc4-5a84-45c7-8543-9c18ba4df95c",
           "type": "EXECUTABLE",
           "meta": {
             "type": "SOURCE"
           },
           "executable": "node /usr/share/engines/worker-scripts/SignalGenerator.js",
           "config": {
             "sampleRate": 1000,
             "amplitudes": [1, 2, 3, 4, 5, 6, 7, 8, 9],
             "frequencies": [2, 3, 5, 6, 11, 23, 30, 50, 75]
           }
         },
         {
           "id": "9c1d72f3-88d9-4195-a896-d4608cd8c9a2",
           "type": "EXECUTABLE",
           "meta": {
             "type": "PROCESSOR"
           },
           "executable": "node /usr/share/engines/worker-scripts/FFT.js",
           "config": {
             "windowSize": 1024,
             "hopSize": 512
           }
         },
         {
           "id": "a297523e-ab4b-41d9-b29c-c434eb4c9723",
           "type": "EXECUTABLE",
           "meta": {
             "type": "OUTPUT"
           },
           "executable": "node /usr/share/engines/worker-scripts/WebSocket.js",
           "config": {
             "port": 36006
           }
         }
       ],
       "pipes": [
         {
           "id": "50198da6-2426-4276-9ba4-d30f396f3d54",
           "source": "94f92dc4-5a84-45c7-8543-9c18ba4df95c",
           "destination": "9c1d72f3-88d9-4195-a896-d4608cd8c9a2"
         },
         {
           "id": "c8d8d431-96d5-4b56-9ea5-3a42b7a6f7bb",
           "source": "9c1d72f3-88d9-4195-a896-d4608cd8c9a2",
           "destination": "a297523e-ab4b-41d9-b29c-c434eb4c9723"
         }
       ]
     }'

   Response:

   {
     "id": "cdc566b5-0221-4018-a99f-23265af1e04d",
     "success": true
   }

2. Start the stream:

   curl -X POST http://localhost:42069/stream/streams/cdc566b5-0221-4018-a99f-23265af1e04d/signal \
     -d "signal=start"

   Response:

   {
     "id": "cdc566b5-0221-4018-a99f-23265af1e04d",
     "success": true
   }

3. Check if the stream is running:

   curl -X GET http://localhost:42069/stream/streams/cdc566b5-0221-4018-a99f-23265af1e04d

   Response:

   {
     "id": "cdc566b5-0221-4018-a99f-23265af1e04d",
     "meta": {
       "name": "Realtime Processing Stream"
     },
     "status": "RUNNING",
     "nodes": [
       {
         "id": "94f92dc4-5a84-45c7-8543-9c18ba4df95c",
         "type": "EXECUTABLE",
         "status": "RUNNING"
       },
       {
         "id": "9c1d72f3-88d9-4195-a896-d4608cd8c9a2",
         "type": "EXECUTABLE",
         "status": "RUNNING"
       },
       {
         "id": "a297523e-ab4b-41d9-b29c-c434eb4c9723",
         "type": "EXECUTABLE",
         "status": "RUNNING"
       }
     ],
     "pipes": [
       {
         "id": "50198da6-2426-4276-9ba4-d30f396f3d54",
         "source": "94f92dc4-5a84-45c7-8543-9c18ba4df95c",
         "destination": "9c1d72f3-88d9-4195-a896-d4608cd8c9a2"
       },
       {
         "id": "c8d8d431-96d5-4b56-9ea5-3a42b7a6f7bb",
         "source": "9c1d72f3-88d9-4195-a896-d4608cd8c9a2",
         "destination": "a297523e-ab4b-41d9-b29c-c434eb4c9723"
       }
     ]
   }

4. Connect to websocket output (using JavaScript in web browser or Node.js):

   const socket = new WebSocket('ws://localhost:36006');
   
   socket.onopen = () => {
     console.log('Connected to data stream');
   };
   
   socket.onmessage = (event) => {
     const data = JSON.parse(event.data);
     // Process and visualize data
     console.log('Received data:', data);
   };
   
   socket.onclose = () => {
     console.log('Disconnected from data stream');
   };

5. Stop the stream when done:

   curl -X POST http://localhost:42069/stream/streams/cdc566b5-0221-4018-a99f-23265af1e04d/signal \
     -d "signal=stop"

   Response:

   {
     "id": "cdc566b5-0221-4018-a99f-23265af1e04d",
     "success": true
   }

Next Steps

• Explore best practices for using the Instinct API
• See the troubleshooting guide for common issues