homebridge-grumptech-netnanny

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.

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 cable_modem
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

1. Fork it!
2. Create your feature/fix branch: git checkout -b my-new-feature
3. Commit your changes: git commit -am 'Add some feature'
4. Push to the branch: git push origin my-new-feature
5. 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.