A NodeJS gateway to interface the Freebox Home API and curl action, setting up a minimalist version of the Freebox Home APIs.
-
✅ 100 % free and open-source
-
✅ Engage/Disengage primary and secondary alarm
-
✅ Get door/motion/alarm status
-
✅ Self-hosted
Few endpoint are exposed in this API such as :
Endpoint | Description |
---|---|
/api/node/{id} | Get the status of a node by it's id. |
/api/node/list | Returns the list of the available nodes (only ids). |
/api/ping | Will just if tell the server is up. |
/api/fbx/rights | Will return a boolean value to show wether the app has home access. |
/api/fbx/auth | Will return a boolean value to show wether the app has been auth. |
/api/refresh/:id | Update the refresh timeout for the node. |
/api/alarm/main | Will turn on primary alarm. |
/api/alarm/target | Will return futher state of alarm. |
/api/alarm/secondary | Will turn on secondary alarm. |
/api/alarm/state | Will return current state of alarm (strange behavior). |
/api/alarm/off | Will turn off alarm. |
- 1: armed
- 0: not armed
- 2: secondary alarm
- 4: Alert
IMPORTANT due to security, API allows only localhost domain. You need to use network mode host and your 8888 port available
# Run the container
$ docker run \
-v /etc/localtime:/etc/localtime:ro \
-v /home/thomas/freeboxAPI:/usr/src/app/credentials \
-e "PUID=1000" \
-e "PGID=1000" \
--restart always \
--name freebox-security-api \
--network=host \
thomaslacaze/freebox-security-api
See here
You need to install NodeJS, npm and pm2.
$ git clone https://github.com/LacazeThomas/freebox-security-API.git
$ cd freebox-security-API/src
$ pm2 start index.js
More information here
After starting the program, you need to give him the right to access your Freebox Home API.
$ curl http://localhost:8888/api/fbx/auth
You box will ask you to give the app access to your Freebox Home API (taping the ✅ on the box's display) :
[13:32:41][11/1/2021] [!] Pending access, check your box
[13:32:43][11/1/2021] [i] Trying again, attempt 1
[13:32:43][11/1/2021] [!] Pending access, check your box
[13:32:45][11/1/2021] [i] Trying again, attempt 2
Give the right permission to API, you need to log into freebox OS (http://mafreebox.freebox.fr/), go into "Paramètres de la Freebox" > "Gestion des accès" and allow the "Freebox-security-API" app to access Gestion de l'alarme et maison connectée (you can disable other unused rights) :
[11:48:48][11/2/2021] [!] Insufficient rights to request home api (home). Trying again...
[11:48:48][11/2/2021] [!] Insufficient rights to request home api (home). Trying again...
After that, you can start the configuration of homeassistant. Please check that your log is all good :
[11:49:22][11/2/2021] [i] Session started
[11:49:22][11/2/2021] [i] Updated credentials
Try to engage primary alarm to test :
$ curl -X GET http://localhost:8888/api/alarm/main
$ curl -X GET http://localhost:8888/api/node/list
> [{"id":58,"type":"alarm"},{"id":65,"type":"camera"},{"id":67,"type":"dws"}]
My alarm ID is 58, my camera ID is 65 and my door sensor is 67. No need to use ID with alarm and camera
In this case my homeassistant configuration is :
switch:
- platform: command_line
switches:
alarm:
command_on: "curl -X GET http://localhost:8888/api/alarm/main 2>/dev/null"
command_off: "curl -X GET http://localhost:8888/api/alarm/off 2>/dev/null"
command_state: "curl -X GET http://localhost:8888/api/alarm/target 2>/dev/null"
value_template: '{{ value == "1" }}'
binary_sensor:
- platform: command_line
command: "curl -X GET http://localhost:8888/api/node/67 2>/dev/null"
name: "ouverture porte"
payload_on: "1"
payload_off: "0"
device_class: "door"
🌟 You are all set!