Package: idun-guardian-client
User guide and documentationWhat can you do with the Python SDK?You can use the Python SDK to search for the device.You can use the Python SDK to connect and record data from the earbud.You can download the data to your local machine.PrerequisitesPython 3.10, if you already have another python version installed and you do not want to create a virtual environment to run the SDK, then you have to install Python 3.10 andset it as your default Python.If you have conflicts with other packages when installing the Python SDK:UseCondawhich will create an environment and configure your python version to the correct one with the following command:condacreate-nidun_envpython=3.10orUsePipenvwhich will create your virtual environment manually using the following command.pipenvinstall--python3.10Quick installation guideCreate a new repository or folderOpen 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:condaactivateidun_envorpipenvshellAfter the environment is activated, install the Python SDK using the following command:With aconda environmentuse the following command:pipinstallidun-guardian-clientorWith apipenv environmentuse the following command:pipenvinstallidun-guardian-clientAfter 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:piplistHow to use the Python SDKYou can also download all the SDK example files from ourGitHub repository, or copy and paste it from the examples below.Example 1: Search for the deviceCreate a new file inside the folder where you created your environment and name itsearch.pyOpen the terminal in the folder and activate your virtual environment using the steps from theQuick installation guide.Open thesearch.pyfile and copy the code from step 1 below.Activate the virtual environmentonlyif you have not already done so by using:condaactivateidun_envorpipenvshellRun the following command in the terminal to run the code after you have activate the enviroment:pythonsearch.pyRecommendation of steps to follow which is elaborated further belowSearch for the deviceCheck the battery levelCheck the impedanceRecord data from the earbudDownload the data from the cloud using the recording IDPre Recording1. Search the earbud manuallyTo search for the earbud, you need to run the following command in your python shell or in your python script:importasynciofromidun_guardian_clientimportGuardianClientbci=GuardianClient()device_address=asyncio.run(bci.search_device())Follow the steps in the terminal to search for the earbud with the nameIGEBIf 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:-----Availabledevices-----

Index|Name|Address
----------------------------0|IGEB|XX:XX:XX:XX:XX:XX1|IGEB|XX:XX:XX:XX:XX:XX2|IGEB|XX:XX:XX:XX:XX:XX
----------------------------For Mac OS:-----Availabledevices-----
Index|Name|UUID
----------------------------0|IGEB|XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX1|IGEB|XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX2|IGEB|XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
----------------------------Enter the index number of the device you want to connect to.2. Check battery levelTo read out the battery level, you need to run the following command in your python shell or in your python script:importasynciofromidun_guardian_clientimportGuardianClientbci=GuardianClient()bci.address=asyncio.run(bci.search_device())asyncio.run(bci.start_battery())3. Check impedance valuesTo read out the impedance values, you need to run the following command in your python shell or in your python script:importasynciofromidun_guardian_clientimportGuardianClientIMPEDANCE_DURATION=5# duration of impedance measurement in secondsMAINS_FREQUENCY_60Hz=False# mains frequency in Hz (50 or 60), for Europe 50Hz, for US 60Hz# Get device addressbci=GuardianClient()bci.address=asyncio.run(bci.search_device())# start a recording sessionasyncio.run(bci.start_recording(recording_timer=IMPEDANCE_DURATION,mains_freq_60hz=MAINS_FREQUENCY_60Hz,impedance_measurement=True))Recording4. Start a recordingTo start a recording with a pre-defined timer (e.g.100in seconds), you need to run the following command in your python shell or in your python script:importasynciofromidun_guardian_clientimportGuardianClientEXPERIMENT:str="Sleeping"RECORDING_TIMER:int=36000# 10 hours in secondsLED_SLEEP:bool=FalseSENDING_TIMEOUT:float=2# No sending receipt time before interruptBI_DIRECTIONAL_TIMEOUT:float=20# No bi-directional data receiving before interrupt# start a recording sessionbci=GuardianClient()bci.address=asyncio.run(bci.search_device())# start a recording sessionasyncio.run(bci.start_recording(recording_timer=RECORDING_TIMER,led_sleep=LED_SLEEP,experiment=EXPERIMENT,sending_timout=SENDING_TIMEOUT,bi_directional_receiving_timeout=BI_DIRECTIONAL_TIMEOUT,))To stop the recording, either wait for the timer to run out or interrupt the recordingwith Mac OS enter the cancellation command in the terminal running the script, this would beCtrl+.orCtrl+Cwith Windows enter the cancellation command in the terminal running the script, this would beCtrl+CorCtrl+Shift+CPost Recording4. Get all recorded infoTo download the data, you need to first get the list of all your recordings and choose the one you would like to downloadRun the following command in your python shell or in your python script:fromidun_guardian_client.igeb_apiimportGuardianAPIapi=GuardianAPI()# get a list of all recordingsrecording_list=api.get_recordings_info_all(device_id="XX-XX-XX-XX-XX-XX")# Device ID is derived from the MAC address of the earbud and in the log file5. Get recording infoTo list the information on a specific recording, you need to run the following command in your python shell or in your python script:fromidun_guardian_client.igeb_apiimportGuardianAPIapi=GuardianAPI()# get single recordingapi.get_recording_info_by_id(device_id="XX-XX-XX-XX-XX-XX",recording_id="xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")5. Download recordingTo download the data insert thedevice_idalong with therecording_idand run the following command in your python shell or in your python scriptfromidun_guardian_client.igeb_apiimportGuardianAPIapi=GuardianAPI()# download recordingapi.download_recording_by_id(device_id="XX-XX-XX-XX-XX-XX",recording_id="xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx")# The info about th recording can be found in the log fileAdding meta data to recording6. Post New Metadata for a RecordingThis example illustrates how to use create_metadata.py to post new metadata for a specific recording. This script will create a new metadata entry, and this metadata will be linked to a returned metadata ID.importasynciofromidun_data_modelsimport(Metadata_in,)fromconfigimportPASSWORDfromidun_guardian_client.igeb_metadataimportMetadataClient# ConfigurationDEVICE_ID="XX-XX-XX-XX-XX-XX"# Replace with your device ID, e.g., "XX-XX-XX-XX-XX-XX"RECORDING_ID="xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx"# Replace with your recording ID, e.g., "py-e852d8d6-9235-4b4b-95a9-7a30f1076f55"DISPLAY_NAME="test"# Display name for the metadataEXPERIMENT_NAME="nap"# Name of the experiment# Initialize MetadataClientclient=MetadataClient(DEVICE_ID,RECORDING_ID,PASSWORD)# Create Metadatametadata_markers=asyncio.run(client.create_metadata(Metadata_in(displayName=DISPLAY_NAME,experiment_name=EXPERIMENT_NAME,),))7. Create Markers for a RecordingThis example demonstrates how to use the create_markers.py script to add new markers to an existing metadata ID. The script creates new marker entries, which will be added to the specified metadata. Note: Before running this script, you should have already created metadata for the recording using create_metadata.py.importasyncioimportnumpyasnpfromdatetimeimportdatetimefromidun_data_models.rest_metadataimportMarkerfromconfigimportPASSWORDfromidun_guardian_client.igeb_metadataimportMetadataClient# ConfigurationMETA_DATA_ID="19"# Replace with your metadata IDDEVICE_ID="XX-XX-XX-XX-XX-XX"# Replace with your device ID, e.g., "XX-XX-XX-XX-XX-XX"RECORDING_ID="xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx"# Replace with your recording ID# Generate MarkersMARKERS=[Marker(timestamp=datetime.now(),marker={"sleepy":np.random.randint(10)})for_inrange(100)]# Initialize MetadataClientclient=MetadataClient(DEVICE_ID,RECORDING_ID,PASSWORD)# Create Markersresponse=asyncio.run(client.create_markers(META_DATA_ID,MARKERS))# Output Resultifresponse:print(f"Successfully added markers to the metadata ID '{META_DATA_ID}' "f"associated with the recording ID '{RECORDING_ID}'. "f"The following markers were added:\n{MARKERS}")7. Create Markers and Meta data for a RecordingThis example shows you how to use a Python script to post both new metadata and markers for a specific recording. The script will create a new metadata entry along with markers, and this metadata will be associated with a returned metadata ID. Before running this script, make sure you have set up the recording for which you are creating metadata and markers.importasyncioimportnumpyasnpfromdatetimeimportdatetimefromidun_data_modelsimportMetadata_in,MarkerfromconfigimportPASSWORDfromidun_guardian_client.igeb_metadataimportMetadataClient# ConfigurationDEVICE_ID="XX-XX-XX-XX-XX-XX"# Replace with your device ID, e.g., "XX-XX-XX-XX-XX-XX"RECORDING_ID="xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx"# Replace with your recording IDDISPLAY_NAME="last_test"# Optional name for the metadataEXPERIMENT_NAME="nap"# Experiment name from Metadata_in enum class# Generate MarkersMARKERS=[Marker(timestamp=datetime.now(),marker={"last_sleep_event":np.random.randint(10)})for_inrange(100)]# Initialize MetadataClientclient=MetadataClient(DEVICE_ID,RECORDING_ID,PASSWORD)# Create Metadata and Markersmetadata_markers=asyncio.run(client.create_metadata(Metadata_in(displayName=DISPLAY_NAME,experiment_name=EXPERIMENT_NAME,markers=MARKERS,),))# Output Resultprint(f"Succesfully created the metadata:\n{metadata_markers}with metadata ID:{metadata_markers.id}")8. List meta data for a recording and metadata IDThis example demonstrates how to retrieve metadata associated with a specific recording. It fetches the metadata based on the metadata ID and the recording ID. Before running this script, ensure you have already posted metadata for the recording.importasyncioimportosfromconfigimportPASSWORDfromidun_guardian_client.igeb_metadataimportMetadataClient# ConfigurationMETA_DATA_ID="19"# Replace with the metadata ID associated with your recordingDEVICE_ID="XX-XX-XX-XX-XX-XX"# Replace with your device ID, e.g., "XX-XX-XX-XX-XX-XX"RECORDING_ID="xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx"# Replace with your recording ID# Initialize MetadataClientclient=MetadataClient(DEVICE_ID,RECORDING_ID,PASSWORD)# Fetch Metadatamarkers_list=asyncio.run(client.get_metadata(META_DATA_ID))# Display Resultsprint(f"Listing the metadata associated with the recording ID{RECORDING_ID}")foren,metadatainenumerate(markers_list):print(f"{metadata}\n")9. List all markers for a recording and metadata IDThis example demonstrates how to add new markers to an existing metadata ID. The new markers will be associated with a given recording and metadata ID. To execute this script, make sure you have already created metadata using the create_metadata.py example.importasyncioimportnumpyasnpfromdatetimeimportdatetimefromidun_data_models.rest_metadataimportMarkerfromconfigimportPASSWORDfromidun_guardian_client.igeb_metadataimportMetadataClient# ConfigurationMETA_DATA_ID="19"# Replace with your metadata ID associated with the recordingDEVICE_ID="XX-XX-XX-XX-XX-XX"# Replace with your device ID, e.g., "XX-XX-XX-XX-XX-XX"RECORDING_ID="xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx"# Replace with your recording ID# Create markersMARKERS=[Marker(timestamp=datetime.now(),marker={"sleepy":np.random.randint(10)})for_inrange(100)]# Initialize MetadataClientclient=MetadataClient(DEVICE_ID,RECORDING_ID,PASSWORD)# Add Markers to Metadataresponse=asyncio.run(client.create_markers(META_DATA_ID,MARKERS))# Display Resultsifresponse:print(f"Successfully added markers to metadata ID '{META_DATA_ID}' "f"associated with recording ID '{RECORDING_ID}'."f" The following markers were added:\n{MARKERS}")10. List all meta data for a recordingThis example demonstrates how to list all metadata entries associated with a specific recording. You can specify the number of entries to be returned in one request (LIMIT) and, if needed, where to start fetching new metadata (CURSOR).importasynciofromdatetimeimportdatetimefromidun_data_modelsimport(Metadata_in,Metadata_out,Marker,MAX_MARKER_COUNT,)fromconfigimportPASSWORDfromidun_guardian_client.igeb_metadataimportMetadataClient# ConfigurationDEVICE_ID="XX-XX-XX-XX-XX-XX"# Replace with your device IDRECORDING_ID="xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx"# Replace with your recording IDLIMIT=100# Number of metadata entries to return in one request, default is 3CURSOR=1# The ID of the last entry in the previous query, if needed# Initialize MetadataClientclient=MetadataClient(DEVICE_ID,RECORDING_ID,PASSWORD)# List Metadatametadata_list=asyncio.run(client.list_metadata(params={"limit":LIMIT,# "cursor": CURSOR,  # Uncomment if you want to use a cursor},))# Display Resultsprint(f"Listing the metadata associated with recording ID '{RECORDING_ID}'")foren,metadatainenumerate(metadata_list):print(f"Metadata ID:{metadata.id}:{metadata}\n")