====== Fonctionnement de l'API  ======

===== Principe de fonctionnement =====

L'API de transmission des données (Abrégée API dans cette page) permet de se connecter au casque neuronal et de traiter à bas niveau les données reçues, avant de les envoyer vers la suite du traitement du signal.\\ 

^Fonctionnalités de l'API:^
|Lister tous les ports USB susceptibles de contenir la clé USB du casque|
|Se connecter au casque|
|Récupérer les valeurs des électrodes|
|Les stocker dans un tampon (Taille réglable selon vos besoins)|
|Appliquer un filtre 50Hz de 1er ordre sur les valeurs|
|Envoyer le tampon vers une autre fonction toutes les x valeurs reçues (x réglable)|



===== Comment utiliser notre API de transmission des données =====

==== Modifier du code ====

Tout le code est modifiable tant que vous ne le détruisez pas. Ça serait dommage que le programme ne fonctionne plus, non ? m( \\ 
Les constantes de base sont également dans l'API si vous voulez modifier les valeurs par défaut.


==== Installation des dépendances ====


Pour utiliser notre programme en Python, il faut installer certaines dépendances via PIP (ou Conda selon l'IDE python). 
<code bash>
Sur PIP (livré avec une installation classique de Python): 
    pip install <nom de la dépendance>

Sur Conda:
    conda install <nom de la dépendance>
</code>

^Liste des dépendances^
|pyOpenBCI|
|scipy|
|numba|
|numpy|
|pyserial|
|xmltodict|
|Cython|
|mne|
|Possiblement plus...|



==== Importer l'API ====

Pour importer notre code python, il faut placer le programme **API.py** dans le programme principal (ou tout autre programme devant utiliser l'API) 
<code python>
import API.py

    [OU]

from API.py import API
</code>

==== Utiliser l'API ====

Pour utiliser l'API, il suffit d'appeler la classe **API**, de lui spécifier le nombre de valeurs avant d'envoyer les résultats (Défaut : 10), de donner la fonction de retour prenant comme paramètre un tableau bidimensionnel, puis d'appeler **start()**.

La connexion au casque prend un peu de temps lors de l'appel de **api.connect(port)** et cette fonction est bloquante. L'appel de **start()** provoque un multithreading, rendant cette fonction non bloquante et permettant de faire autre chose une fois **start()** appelé. Il est important d'appeler **stop()** lors de la fin de vie du programme sans quoi le thread restera ouvert et devra être **kill**. 

<code python>

def returnFct(data):
    print(data)
    
envoyerTouteLesXValeurs = 50

api = API(dataInterval=envoyerTouteLesXValeurs)

api.connect("COM3")
api.setDataReceivedFunction(returnFct)
api.start()


#Si on veut arrêter la récupération
api.stop()

#Si on veut déconnecter le casque
api.disconnect()


</code>

Pour redimensionner le tableau tampon, il faut appeler la fonction **resizeBuffer** qui aura pour effet de détruire les valeurs stockées avant de redimensionner le tampon. La valeur par défaut est 250.

<code python>

api.resizeBuffer(newLength)

</code>

Pour lancer une récupération unique de données plutôt qu'un stream de données, il existe une fonction **acquire** qui récupère des données correspondant à X secondes d'acquisition et retourne ces valeurs sans devoir définir une fonction de retour ou de handler particulier. Idéal pour récupérer des données sous forme de **Dataset**.

**Important : Il est impossible d'appeler __acquire()__ et __start()__ en simultanéité, ces 2 fonctions utilisant la même architecture commune interne posant des conflits graves si utilisés en même temps !**

<code python>

#Récupère 20 secondes de valeurs, attend la fin de la récupération puis retourne les valeurs
data = api.acquire(20)

</code>