Gateway
Fonctionnalités
Paramètre réseau
• Récupération de l’adresse IP par DHCP.
- On ne récupère que les paramètres réseau de base: IP, netmask et gateway.
- La gateway ne récupère pas le serveur DNS, ni le proxy si il y en a un.
- La gateway ne fonctionne pas si un proxy est utilisé.
• Recuperation de l’IP api.the-keys.fr.
- On utilise le serveur DNS de google: 8.8.8.8
Taches récurrentes
• La gateway scanne en continu les serrures. Si une serrure annonce qu’elle doit se synchroniser (pour envoyer les informations d’ouverture ou fermeture), la gateway synchronise la serrure
• Toutes les 5s, elle envoie au serveur les informations sur les serrures qu’elle voit. Le serveur en retour renvoie les informations sur les éventuelles synchronisation à faire
• Lors de la synchronisation, si un nouveau firmware est disponible, elle se met à jour
• Dans les informations de synchronisation de la serrure, il y a la mise à jour éventuelle du firmware des serrures
Serveur WS
Liste des serrures
curl http://<ip>/lockers
Réponse:
{"status": "ok", "devices": [{"identifier": 45961123, "rssi": -71, "battery":4065}]}Synchroniser la gateway
curl http://<ip>/synchronize
Réponse:
{"status": "ok", "code": 0}
Erreurs:
• Si la gateway est occupée (autre action en cours):
• {"status": "500", "message": "busy"}Synchroniser une serrure
curl -d "identifier=<id locker>" http://<ip>/locker/synchronize
Réponse:
{"status": "0", "code": "ok"}
Erreurs:
• Si la gateway est occupée (autre action en cours):
{"status": "500", "message": "busy"}
• Serrure non détectée:
status = 1
La serrure n'est pas vue par la gateway
• Serrure non compatible:
status = 2
La serrure n'est pas compatible avec la gateway
• Données invalides
status = 3
Le serveur api.the-keys.fr a renvoyé des données de synchronisation invalides (c'est un cas possible sur un problème serveur)
• Erreur lors de la synchronisation
status = 4
Erreur de connexion avec la serrureMise à jour de la gateway
La gateway sera mise à jour, même si le firmware est déjà à jour.
curl http://<ip>/update
Erreurs:
• Si la gateway est occupé (autre action en cours):
{"status": "500", "message": "busy"}
• Firmware invalide
status = 1
Le cas standard est une erreur de téléchargement
• Erreur générique
status = 2
Si le serveur ne renvoie pas le firmware.Mise à jour d’une serrure
curl -d "identifier=<id locker>" http://<ip>/locker/updateOuvrir une serrure
• Création du partage
Pour utiliser la gateway depuis une box domotique, il faut d’abord créer un partage entre la serrure et la gateway.
Chaque gateway a un id unique que vous pouvez retrouver sur sa notice
Il faut ensuite créer le partage en utilisant le WS « createWithAccessory »:
def createShare(self, name, locker, gateway):
data = {}
data["partage_accessoire[description]"] = ""
data["partage_accessoire[nom]"] = name
headers = {"Authorization": "Bearer %s"%self.token}
r = requests.post("https://%s/fr/api/v2/partage/create/%s/accessoire/%s"%(self.host, locker, gateway), headers=headers, data=data)
data = json.loads(r.text)
code=data["data"]["code"]Le WS renvoie en retour le code du partage.
• Génération du hmac
On utilise un timestamp pour générer le hmac. Le timestamp est unique par requête et on ne peut pas utiliser un timestamp plus ancien que le précédent.
Exemple en python de la génération du hmac:
ts = str(int(time.time()))
hm = hmac.new(code, ts.encode("ascii"), "sha256")
hash=base64.b64encode(hm.digest()) • Ouverture
Pour l’ouverture, on envoie le timestamp et le hash:
curl -d "identifier=<id locker>&hash=<hash>&ts=<ts>" http://<ip>/open
Réponse:
{"status": "0", "code": "ok"}
Erreur:
• Paramètre manquant:
status = 400
Le code contient les informations sur le paramètre manquant (timestamp, hash ou identifier)
• La serrure n'est pas partagée
status = 32
La gateway ne peut pas valider le hmac si il n'y a pas de partage avec elle.
• Hmac invalide
status = 33
• La serrure n'est pas detectée
status = 34
• La serrure n'est pas compatible
status = 35
• Clé invalide
status = 36
La gateway a essayé d'ouvrir, mais la serrure a refusé la clef.
Vérifier que le partage existe et que la serrure est synchronisé dans ce cas.
• Autre erreur
status = 37
Tous les cas d'erreurs non identifiés:
- La connexion à la serrure a échoué
- La connexion s'est coupée
- La serrure renvoie un timeoutFermer une serrure
La fermeture se fait comme l’ouverture. il n’y a que l’url qui change:
curl -d "identifier=<id locker>&hash=<hash>&ts=<ts>" http://<ip>/closeStatus de la gateway
A partir de la version 17
curl http://<ip>/status
reponse:
{"version": "16", "current_status": "Scanning..."}Status d’une serrure
La récupération du statut se fait comme pour l’ouverture. il n’y a que l’url qui change:
curl -d "identifier=<id locker>&hash=<hash>&ts=<ts>" http://<ip>/locker_status
Il y a 3 codes possibles en réponse:
• Etat inconnue (code 0x30)
Ce cas se produit quand la serrure vient de démarrer (après une mise à jour par exemple).
• Porte fermée (code 0x31)
• Porte ouverte (code 0x32)Test rapide
Telechargez les 2 fichiers python qui permettent d’interagir avec la gateway: https://github.com/benoit-tk/demo_python
./test.py --help
usage: test.py [-h] [-d] [-i IDENTIFIER] [--host HOST] [-c CODE] action
positional arguments:
action open, close, search, synchronize, update,
synchronize_locker, update_locker
optional arguments:
-h, --help show this help message and exit
-d, --debug
-i IDENTIFIER, --identifier IDENTIFIER
locker identifier
--host HOST host
-c CODE, --code CODE code
Par exemple, pour ouvrir:
./test.py --host 192.168.0.26 -i 45961123 -c 'Zmo1sps2OVyCFtl1' open