1. Home
  2. Developers
  3. Command the lock via the gateway
Searching...

Command the lock via the gateway

Gateway

Features

Network parameters

– IP address retrieval via DHCP.

  • Only the basic network parameters are retrieved: IP, netmask and gateway.
  • The gateway does not retrieve the DNS server, nor the proxy if there is one.
  • The gateway does not work if a proxy is used.

– Recovering the IP api.the-keys.fr.

  • We are using the google DNS server: 8.8.8.8

Recurring tasks

– The gateway continuously scans the locks. If a lock announces that it needs to synchronize (to send opening or closing information), the gateway synchronizes the lock

– Every 5s, it sends the server information about the locks it sees. The server in return sends back information about any synchronization to be done

– When synchronizing, if new firmware is available, it updates

– In the lock sync information, there is the possible update of the locks firmware

Serveur WS

List of locks

curl http://<ip>/lockers

Response: 

{"status": "ok", "devices": [{"identifier": 45961123, "rssi": -71, "battery":4065}]}

Synchronize the gateway

curl http://<ip>/synchronize

Response:

{ "status": "ok", "code": 0}

Errors:

 - If the gateway is busy (other action in progress): 

    - { "status": "500", "message": "busy"}

Synchronize the lock

curl -d "identifier=<id locker>" http://<ip>/locker/synchronize

Response:

{ "status": "0", "code": "ok"}


Errors:

   - If the gateway is busy (other action in progress): 

     { "status": "500", "message": "busy"}


    - Lock not detected:

     status = 1

     Lock is not seen by the gateway


   - Lock not compatible:

     status = 2

     Lock is not compatible with the gateway


   - Invalid data

     status = 3 

     The api.the-keys.fr server has returned invalid synchronisation data (this is a possible case of a server problem)


   - Error during synchronisation

     status = 4

     Connection error with the lock

Update the gateway

The gateway will be updated, even if the firmware is already up to date.

curl http://<ip>/update


Errors:

    - If the gateway is busy (other action in progress): 

     { "status": "500", "message": "busy"}


    - Invalid firmware

      status = 1

      The standard case is a download error


    - Generic error

      status = 2

      If the server does not return the firmware.

Update the lock

curl -d "identifier=<id locker>" http://<ip>/locker/update

Open a lock

– Creating the share

To use the gateway from a home automation box, you must first create a share between the lock and the gateway. 

Each gateway has a unique id that you can find on its notice

Then you need to create the share using the 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"]

The WS returns the code for the share.

• Generating the hmac

A timestamp is used to generate the hmac. The timestamp is unique per request and you can’t use an older timestamp than the previous one.

The timestamp is unique per request and we can’t use an older timestamp than the previous one.

Python example of generating the hmac:

ts = str(int(time.time()))

hm = hmac.new(code, ts.encode("ascii"), "sha256")

hash=base64.b64encode(hm.digest())

• Opening

For opening, we send the timestamp and hash:

curl -d "identifier=<id locker>&hash=<hash>&ts=<ts>" http://<ip>/open

Response:

{ "status": "0", "code": "ok"}


Error:

   - Missing parameter: 

     status = 400

     The code contains information about the missing parameter (timestamp, hash or identifier)


  - The lock is not shared

      status = 32

     The gateway cannot validate the hmac if it is not shared with it.


  - Invalid hmac

       status = 33


   - The lock is not detected

      status = 34


   - Lock is not compatible

     status = 35


   - Invalid key

     status = 36

     The gateway tried to open, but the lock refused the key. 

     Check that the share exists and that the lock is synchronised in this case.

   - Other error

     status = 37

     All error cases not identified: 

        - Connection to the lock has failed

        - The connection has been disconnected

        - Lock returns a timeout

Closing a lock

Closing is done just like opening. only the url changes:

curl -d "identifier=<id locker>&hash=<hash>&ts=<ts>" http://<ip>/close

Status of the gateway

As of version 17

curl http://<ip>/status

response: 

{"version": "16", "current_status": "Scanning..."}

Status of a lock

Recovering the status is the same as for opening. only the url changes:

curl -d "identifier=<id locker>&hash=<hash>&ts=<ts>" http://<ip>/locker_status

There are 3 possible codes in response:

   - Unknown status (code 0x30)

     This case occurs when the lock has just boot (after an update for example).

   - Door closed (code 0x31)

   - Door open (code 0x32)

Quick test

Unload the 2 python files that allow to interact with the 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

For example, to open:

./test.py --host 192.168.0.26 -i 45961123 -c 'Zmo1sps2OVyCFtl1' open