freebox-security-API

A NodeJS gateway to interface the Freebox Home API and curl action, setting up a minimalist version of the Freebox Home APIs.

🧐 Features

• ✅ 100 % free and open-source

• ✅ Engage/Disengage primary and secondary alarm

• ✅ Get door/motion/alarm status

• ✅ Self-hosted

🔧 Endpoint availables

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.

🔧 Alarm States

• 1: armed
• 0: not armed
• 2: secondary alarm
• 4: Alert

🛠️ Installation Steps

IMPORTANT due to security, API allows only localhost domain. You need to use network mode host and your 8888 port available

🐳 Option 1: Run from Docker run

# 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

🐳 Option 2: Run from Docker-compose

See here

💻 Option 3: Run from source

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

📝 Configuration

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

Configuration with homeassistant

$ 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!

Dockerfile

Dockerfile

License

MIT