Custom Integration: Firewalla

Share your Projects! Custom Integrations
1

Greetings! I’ve published a custom integration for Firewalla MSP API data:

GitHub - BeerDiet/firewalla-home-assistant: A Home Assistant integration for Firewalla. · GitHub

It is a UI-configured integration that connects to a Firewalla MSP endpoint with a personal access token and exposes:

  • Blocked flows, alarms, and rule activity
  • Online and offline box counts
  • Current alarms and rules
  • Top-region statistics
  • Aggregate download and upload traffic
  • Per-box security and activity sensors
  • Per-box top-talker sensors with ranked download and upload attributes
  • Per-network throughput sensors under each box
  • Rule-backed internet block switches for devices and local networks

A few notes:

  • It supports global, group, and box scopes
  • It includes diagnostics, reauthentication, and reconfiguration flows
  • It is available through HACS as a custom integration
  • The repo includes HACS validation and hassfest workflows
  • Make sure to checkout the /examples folder for dashboards showing current network traffic telemetry and top talkers

Installation:

  • Add the repository in HACS as a custom repository
  • Choose the Integration category
  • Install Firewalla
  • Restart Home Assistant

Feedback welcome, especially on:

  • Firewalla MSP API behavior across different scopes
  • Edge cases I may have missed
  • Sensors or attributes that would be useful to add
2

Today I released 0.5.9, which includes a lot more management around API usage limits imposed by Firewalla, which are as follows, according to Firewalla directly.

  • Long-term limit: Default to 3000 requests per day per token. This ensures fair usage and protects against sustained high-volume access.
  • Short-term limit: Default to 100 requests per 5 minutes per token. This helps prevent sudden traffic spikes

Instead of having a configurable static polling interval against Firewalla's API, I've decided to implement an adaptive interval based on current API usage against the imposed limits by Firewalla. To this end, 3 new sensors have been created per MSP account:

  • Calls made to Firewalla's API today
  • Current scan interval (adaptive, polling)
  • Maximum allowed limit (currently 3000, but is configurable in the integration's Config / Reconfigure dialog)

After each call to the API, the scan interval is recomputed. This is mainly due to HA users having the ability to make ad hoc API calls through normal administration of the network (can enable or disable rules, for example).