No project description provided
Project description
User guide and documentation
What can you do with the Python SDK?
- Search for the device.
- 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)
- Download the data to your local machine.
- 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
- Use Conda which will create an environment and configure your python version to the correct one with the following command:
Quick installation guide
-
Create a new repository or folder for your project
-
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.
-
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
-
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
-
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+.
orCtrl+C
- with Windows enter the cancellation command in the terminal running the script, this would be
Ctrl+C
orCtrl+Shift+C
- with Mac OS enter the cancellation command in the terminal running the script, this would be
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
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for idun_guardian_sdk-0.1.3-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a6fda09ac470293604a9c9990fd2810d11113fb448f6e06f028c56f429d6c96a |
|
MD5 | 7452443d89783ab73f17d09801c48205 |
|
BLAKE2b-256 | 02028f4864b8d457dc1c0e9e99d0c0419859a5c305d72247e372ab5688ce141c |