idun-guardian-sdk 0.1.3

No project description provided

User guide and documentation

What can you do with the Python SDK?

1. Search for the device.
2. Connect and record data from the earbud.
   • Get live insights of your data (raw eeg and filtered eeg)
   • Get real time predictions of your data (fft, jaw clench)
3. Download the data to your local machine.
4. Generate Reports

---

Prerequisites

• Python 3.9 - 3.13
• Alternatives if you have conflicts with other packages when installing the Python SDK:
  • Use Conda which will create an environment and configure your python version to the correct one with the following command:

    conda create -n idun_env python=3.10
    

    or
  • Use Pipenv which will create your virtual environment manually using the following command.

    pipenv install --python 3.10
    

    or
  • Create (and activate) a Python virtual environment:

    python -m venv idun_env
    source idun_env/bin/activate
    

---

Quick installation guide

1. Create a new repository or folder for your project

2. Open the terminal in the same folder location or direct to that location within an already open terminal. For Windows you can use command prompt or Anaconda prompt, and Mac OS you can use the terminal or Anaconda prompt.

3. First activate the virtual environment if you have created one by using the following command, this command must always be run before using the python SDK:

   conda activate idun_env
   

   or

   pipenv shell
   

   or

   source idun_env/bin/activate
   

4. After the environment is activated, install the Python SDK using the following command:

   • With a virtual environment (conda or vanilla python venv) activated, use the following command:

   pip install idun-guardian-sdk
   

   or

   • With a pipenv environment use the following command:

   pipenv install idun-guardian-sdk
   

   Alternatively, to install from source:

   • Clone the repository, go to desired branch
   • Run: pip install /path/to/idn-guardian-sdk-light

5. After installing the package, make sure that the dependencies are correctly installed by running the following command and inspecting the packages installed in the terminal output:

   pip list
   

---

How to use the Python SDK

You can find sample scripts from this GitHub repository in examples folder to do basic operations with guardian earbud.

Before getting started, you should have your IDUN API TOKEN. You can configure the token whether by setting IDUN_API_TOKEN Environment Variable or by sending as argument when initializing GuardianClient in Python:

Env Var:

export IDUN_API_TOKEN=my-api-token

or

my_api_token = "xxxxxx"
client = GuardianClient(api_token=my_api_token)

Pre Recording

1. Search the earbud manually

• To search for the earbud, you need to run the following command in your python shell or in your python script:

import asyncio
from idun_guardian_sdk import GuardianClient

client = GuardianClient()

device_address = asyncio.run(client.search_device())

• Follow the steps in the terminal to search for the earbud with the name IGEB

• If there are more than one IGEB device in the area, you will be asked to select the device you want to connect to connect to, a list such as below will pop up in the terminal:

  • For Windows:

  ----- Available devices -----
  
  Index | Name | Address
  ----------------------------
  0     | IGEB | XX:XX:XX:XX:XX:XX
  1     | IGEB | XX:XX:XX:XX:XX:XX
  2     | IGEB | XX:XX:XX:XX:XX:XX
  ----------------------------
  

  • For Mac OS:

  ----- Available devices -----
  Index | Name | UUID
  ----------------------------
  0    | IGEB | XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
  1    | IGEB | XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
  2    | IGEB | XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
  ----------------------------
  

• Enter the index number of the device you want to connect to.

2. Check battery level

• To read out the battery level, you need to run the following command in your python shell or in your python script:

import asyncio
from idun_guardian_sdk import GuardianClient

client = GuardianClient()
client.address = asyncio.run(client.search_device())

asyncio.run(client.check_battery())

**3. [TO BE FIXED] Check impedance values **

• Currently not working in the sdk, will be fixed soon.
• To read out the impedance values, you need to run the following command in your python shell or in your python script:

import asyncio
from idun_guardian_sdk import GuardianClient

IMPEDANCE_DURATION = 5  # duration of impedance measurement in seconds
MAINS_FREQUENCY_60Hz = False
# mains frequency in Hz (50 or 60), for Europe 50Hz, for US 60Hz


# Get device address
client = GuardianClient()
client.address = asyncio.run(client.search_device())

# start a recording session
asyncio.run(
    client.start_recording(
        recording_timer=IMPEDANCE_DURATION,
        mains_freq_60hz=MAINS_FREQUENCY_60Hz,
        impedance_measurement=True)
)

Recording

4. Start a recording

• To start a recording with a pre-defined timer (e.g. 100 in seconds), you need to run the following command in your python shell or in your python script:

import asyncio
from idun_guardian_sdk import GuardianClient

RECORDING_TIMER: int =  60 * 60 * 10  # 10 hours
LED_SLEEP: bool = False

my_api_token = ""


# Example callback function
def print_data(event):
    print("CB Func:", event.message)


if __name__ == "__main__":
    client = GuardianClient(api_token=my_api_token)
    client.address = asyncio.run(client.search_device())

    client.subscribe_live_insights(raw_eeg=True, filtered_eeg=True, handler=print_data)
    # TODO: to be implemented
    # client.subscribe_realtime_predictions(fft=True, jaw_clench=False, handler=print_data)

    # start a recording session
    asyncio.run(
        client.start_recording(
            recording_timer=RECORDING_TIMER,
            led_sleep=LED_SLEEP,
        )
    )

• To stop the recording, either wait for the timer to run out or interrupt the recording
  • with Mac OS enter the cancellation command in the terminal running the script, this would be Ctrl+. or Ctrl+C
  • with Windows enter the cancellation command in the terminal running the script, this would be Ctrl+C or Ctrl+Shift+C

Post Recording

4. Get all recorded info

At the end of recording, the recording ID will be printed, and you can use it to download the data.

If you somehow lose the terminal logs, you can still get info of previous recordings:

from idun_guardian_sdk import GuardianClient

client = GuardianClient()

# get a list of all recordings
recordings = client.get_recordings(status="COMPLETED", limit=10)

print(recordings)

5. Download recording

• To download the recoridng run the following command in your python shell or in your python script

from idun_guardian_sdk import GuardianClient, FileTypes

client = GuardianClient()

client.download_file(recording_id=my_recording_id, file_type=FileTypes.EEG)

Generating Reports

Your recording must have at least 10 minutes of data so the reports can be generated

6. Generate Sleep Report for a Recording

To generate sleep report, you can call generate_and_download_sleep_report

from idun_guardian_sdk import GuardianClient


my_api_token = ""
my_recording_id = ""


if __name__ == "__main__":
    client = GuardianClient(api_token=my_api_token)
    client.generate_and_download_sleep_report(recording_id=my_recording_id)

7. Generate Daytime Report for a Recording

To generate daytime report, you can call generate_and_download_daytime_report

from idun_guardian_sdk import GuardianClient


my_api_token = ""
my_recording_id = ""


if __name__ == "__main__":
    client = GuardianClient(api_token=my_api_token)
    client.generate_and_download_daytime_report(recording_id=my_recording_id)

Development

• setup: poetry install
• build package: poetry build
• build docs: make html