Homebridge Net Nanny
Homebridge Net Nanny, by GrumpTech, is a Homebridge dynamic platform plug-in that publishes metrics measuring the health of a network. This plugin was inspired by Dave Hamilton's, of the Mac Geek Gab, 3-Ping strategy for evaluating network health.
What Problem Does Net Nanny Solve?
When we suffer network problems, it's sometimes hard to figure out whether the problem is on the local area network, a problem with your Internet service provider, or a problem with a service to which you're trying to connect. In order to isolate the problem, a good practice is to open a terminal window and ping your router, then your modem, and then a known-reliable server on the Internet.
The Net Nanny Homebridge plugin is designed to give you this information at a glance from within HomeKit. The Homebridge plugin creates several services to HomeKit:
- a collection of switches called NetNanny Switches. At the present time this collection contains only one switch, called Export History, which will generate an on-demand log of all ping data collected thus far.
- a switch for each ping target that allows the user to control each target separately.
- a set of fake carbon dioxide (CO2) services that will report your network health.
When configured properly, in the Home app, you'll see a set of "Alarm Sensors". These sensors will represent the targets you set up for network testing, e.g. your router, modem, and external server(s). Each target will have three sensors associated with it: one for latency, one for jitter, and one for packet loss. Because we're simulating these services, the sensors will report their metrics in units of ppm (parts per million), but the values are actually milliseconds for latency and jitter and percent for packet loss. In other words, if you see a latency of 8 ppm and a packet loss of 10 ppm, that means its latency is 8ms and the packet loss is 10%.
By having these sensors reporting these three metrics, you can get a sense of what normal looks like, and when things go wrong they could help you isolate the problem between your network and your ISP.
Change Log
The change history can be viewed here
Security Policy
Please refer to our security policy for information on which versions are receiving security updates and how to report security vulnerabilities.
Installation
This plug-in is intended to be used with the homebridge-config-ui-x homebridge management tool. If using homebridge-config-ui-x, simply search for homebridge-grumptech-netnanny for installation, plug-in management, and configuration.
To install the plugin manually:
npm install -g homebridge-grumptech-netnanny
Configuration
homebridge-config-ui-x
This plugin is best experienced when running as a module installed and managed by the homebridge-config-ui-x plugin. When running under homebridge-config-ui-x, visiting the plugin settings will allow you to change the polling interval and the low space alarm threshold, as shown below.
For details on the configuration settings, please refer to the Configuration Settings section below.
Additionally, especially if this system will be running other homebridge modules, it is strongly encouraged to run this plugin as an isolated child bridge. This setting page can be found by clicking on the wrench icon on the plugin and then selecting Bridge Settings. With the child bridge enabled, revisiting the setting page after homebridge is rebooted will show a QR code for pairing to the child bridge. The username (MAC address) and port are randomly generated by homebridge-config-ui-x.
<img src="./assets/config-ui-x_bridgesettings_disabled.png"
alt="homebridge-config-ui-x plugin configuration showing the child bridge disabled"
style="padding:2px 2px 2px 2px; border:2px solid; margin:0px 10px 0px 0px; vertical-align:top;"
width="51.5%">
<img src="./assets/config-ui-x_bridgesettings_enabled.postreboot.png"
alt="homebridge-config-ui-x plugin configuration showing the child bridge active (unpaired)"
style="padding:2px 2px 2px 2px; border:2px solid; margin:0px 10px 0px 0px; vertical-align:top;"
width="30%">
Configuration Settings
| Setting | Description | Field Name | Parameter Type | Data Type | Units | Default | Minimum or Allowed Values | Maximum | Comments |
|---|---|---|---|---|---|---|---|---|---|
| Ping Period | The time, in seconds, to initiate a series of ping requests. | ping_period | Common | Number | Time:seconds | 20 | 6 | N/A | |
| Ping Interval | The time, in seconds, between each ping request. | ping_interval | Common | Number | Time:seconds | 1 | 1 | N/A | |
| Ping Count | The number of ping request for each series. | ping_count | Common | Number | Count | 5 | 3 | N/A | |
| Packet Size | The size, in bytes, of each ping request. | packet_size | Common | Number | Bytes | 56 | 56 | N/A | |
| Enable History Logging | Enables / Disables logging of ping results | enable_history_logging | Common | Boolean | N/A | True | False | True | |
| History Reporting Period | The time, in days, for generating report logs of network performance | history_logging:reporting_period | Common | Number | Time:days | 1 | 0.041667 | 100 | |
| Maximum History Size | Maximum number of result sets to record in the history database | history_logging:maximum_history_size | Common | Number | N/A | 250000 | 2500 | 5000000 | |
| Oretention Period | Number of days to retain history log files. | history_logging:retention_period | Common | Number | Time:days | 30 | 1 | 365 | |
| Target Type | Type of target. | ping_targets:items:target_type | Per Target | String | N/A | ipv4 | uri, ipv4, ipv6, gateway, cable_modem | ||
| Modem Type | Type of cable modem. | ping_targets:items:modem_type | Per Target | String | N/A | other | xfinity, netgear, other | Only valud when the target type is set to _cablemodem | |
| Target Destination | Destination for the ping | ping_targets:items:target_dest | Per Target | String | Not applicable for gateway or cable_modem | ||||
| Packet Loss Limit | The limit, in percent, of lost packets that will be tolerated. | ping_targets:items:loss_limit | Per Target | Number | Percent | 5 | 0 | 100 | |
| Expected Latency | The expected latency, in milliseconds, for the ping. | ping_targets:items:expected_latency | Per Target | Number | Time:milliseconds | 10 | >0 | N/A | |
| Expected Jitter | The expected jitter, in milliseconds, of the ping latency. | ping_targets:items:expected_jitter | Per Target | Number | Time:milliseconds | 1 | >0 | N/A | |
| Peak Expiration Time | The time, in hours, used to reset the peak values. | ping_targets:items:peak_expiration | Per Target | Number | Time:hours | 12 | 0 | N/A | |
| Data Filter Time Window | The time, in seconds, over which to filter the ping results. | data_filter_time_window | Per Target | Number | Time:seconds | 180 | 6 | N/A | Values less than the 'Ping Period' will be ignored. |
| Sensor Alert | Indicates which of the Carbon Dioxide sensors issue CO2 aleets when the data exceeds specified limits. | sensor_alert_mask | Per Target | Number | Bitmask | 7 | 0 | 7 | Bit#0:Time, Bit#1:Packet Loss; Bit#2:Standard Deviation |
Manual Configuration
If you would rather manually configure and run the plugin, you will find a sample config.json file in the ./config folder. It is left to the user to get the plugin up and running within homebridge. Refer to the section above for specifics on the configuration parameters.
Usage
The plugin will create, or restore, a dynamic accessory for each network target specified in the configuration. Each accessory will advertise four services: (1) switch, and (3) carbon dioxide sensors . All of the data presented for the carbon dioxide sensors is the result of the ping results. In an effort to keep outliers from affecting the reported values, the data collected will be run through a filter, as discussed below. In addition to the services provided by each network targer, the plugin will adversise an additional a collection of switch services.
- Power: A switch, with the name of the Target Destination, that controls the active state of the network performance target.
- Latency: The average ping latency, in milliseconds. The peak value is also displayed. Alerts are triggered when the reported value exceeds:
Expected Latency + (3 * Expected Jitter) - Jitter: The jitter, in milliseconds, of the ping latency results. The peak value is also displayed. Alerts are triggered when the reported value exceeds:
Expected Jitter - Packet Loss: The packet loss, in percent. The peak value is also displayed. Alerts are triggered when the reported value exceeds:
Packet Loss Limit - NetNanny-Switches: A collection of switches. At the present time, this collection contains a single switch. This switch will be used perform an off-cycle export of the database and flush all existing data.
When the current value for any of the carbon dioxide sensors exceeds the user-specified expected limits, the sensor’s alert will be set and, in addition, the sensor’s Detected value will be set to abnormal levels, if configured. Each Carbon Dioxide sensor can be configured to not set the Detected value to abnormal when a fault is encountered. Setting the Detected value to abnormal levels should result in am alert noticiation from HomeKit.
Because the ping results can be noisy, the results are filtered using the AVT (Antonyan Vardan Transform) algorithm. The amount of data considered in the filter is implicitly set via the Data Filter Time Window configuration parameter on each network target. The size of the data buffer is computed as the ratio Data Filter Time Window to Ping Period. The larger this ratio, the more ping results that will be considered in the filter. The value reported by the filter is the median value after excluding the data points that are beyond one standard deviation. Therefore, one can assume that the alerts will not be detected until at least half of the Data Filter Time Window has elapsed with raw results that exceed the user specified limits. This should have the tendency to limit false positive detections. However, if the ratio is too small (not enough data in the buffer), then the reporting will be more responsive and alerts will be issued for transient glitches in the network performance that do not necessarially indicate a systemic problem.
It should also be noted, that the Detected value will not be set to abnormal until the Data Filter Time Window has elapsed after startup. This will prevent an occasional bad result from immediately resulting in the detection of abnormal carbon dioxide levels at startup.
When the accessory is inactive, the Active and Low Battery Status are set.
When Enable History Logging is active, the filtered ping results will be stored in an in-memory database. The data will be exported to a CSV data file periodically or upon manual request. The exported data will be saved to a folder named GrumpTechHomebridgeNetNanny located in the homebridge configuration folder. For example, on macOS ~/.homebridge/GrumpTechHomebridgeNetNanny/.
Restrictions
This module operates by using shell commands to the ping and route programs. At this time, the plugin assumes macOS output when parsing the results. While the ping output is consistent across operating systems, the route output is operating system specific. As a result, the gateway/router type selection is limited to macOS and linux.
Known Issues and Planned Enhancements
Refer to the bugs and enhancements listed here
Contributing
- Fork it!
- Create your feature/fix branch:
git checkout -b my-new-feature - Commit your changes:
git commit -am 'Add some feature' - Push to the branch:
git push origin my-new-feature - Submit a pull request
Credits
Many thanks to all the folks contributing to Homebridge and to oznu for homebridge-config-ui-x, allowing for the possibility of this sort of fun and learning.
Special thanks to Dave Hamilton's, and the MacGeekGab podcast for inspiring the idea for this plugin.
License
Refer to LICENSE.md for information regarding licensincg of this source code.