FCC Diagnostics Software Design Description

This document provides a detailed overview of the design specifications for implementing the FCC Diagnostics Feature, including configuration management, database schema, diagnostic workflow, and UI design.

1. Introduction

The FCC Diagnostics Feature is an essential component designed to ensure compliance with Federal Communications Commission (FCC) regulations regarding network latency and speed. This document provides a detailed overview of the design specifications for implementing this feature.

2. Purpose

The primary objectives of the FCC Diagnostics Feature are as follows:

  • Latency Diagnostics: Monitor and analyze network latency to ensure it meets FCC standards.

  • Speed Diagnostics: Evaluate network speed performance against FCC requirements.

  • Automated Diagnostics: Introduce a robust automated diagnostic mechanism triggered from the UpdateGroup module.

  • Configuration Flexibility: Allow customization of diagnostic parameters through the fcc.properties file.

  • Data Integrity: Ensure accurate recording and storage of diagnostic results in dedicated database tables.

3. Scope

The scope of the FCC Diagnostics Feature includes the following key components:

  • Integration with UpdateGroup: Introduce a new UpdateGroup task type, "FCC diagnostics", to initiate diagnostic tasks.

  • Configuration Management: Define diagnostic parameters such as repeat intervals, thresholds, and intervals between data retrievals through the fcc.properties file.

  • Database Schema Expansion: Create new tables (ug_fcc_speed_result, ug_fcc_latency_result) and modify existing ones (ug_fcc, ug_get_param, etc.) to store diagnostic metadata and results.

  • Diagnostic Stages: Implement detailed diagnostic stages including data retrieval, calculation, threshold comparison, and error handling.

  • Error Descriptions: Provide comprehensive descriptions for various diagnostic scenarios to facilitate troubleshooting.

4. Design Overview

The design of the FCC Diagnostics Feature consists of the following components:

  • UpdateGroup Integration: Introduction of a new task type, "FCC diagnostics", within the UpdateGroup module to trigger diagnostic tasks.

  • Configuration Management: Utilization of the fcc.properties file to configure diagnostic parameters such as repeat intervals, thresholds, and data retrieval intervals. (if not exists — default values are used)

  • Database Schema Modification: Creation of new database tables (ug_fcc, ug_fcc_speed_result, ug_fcc_latency_result) and addition of columns to existing tables to accommodate diagnostic data.

  • Diagnostic Workflow: Implementation of a detailed workflow including stages for data retrieval, calculation of WAN usage, comparison with predefined thresholds, and initiation of diagnostic tasks.

  • Error Handling: Provision of descriptive error messages for various diagnostic scenarios to aid in diagnosis and resolution.

5. Detailed Design

5.1. Configuration File (fcc.properties)

The fcc.properties file contains configuration parameters for the FCC Diagnostics Feature, including:

  • fcc.repeat: Number of times to repeat the diagnostic tests.

  • fcc.interval: Interval between consecutive diagnostic tests (in minutes).

  • wan_usage.repeat: Number of times to repeat the WAN usage test in case of detection.

  • wan_usage.interval: Interval between WAN usage tests (in seconds).

  • wan_usage.retrieve.interval: Interval between GetParameterValues tasks for retrieving BytesSent/BytesReceived parameters.

  • latency.success: Latency success threshold (in milliseconds).

  • speed.success: Speed success percentage threshold.

5.2. Database Schema

The database schema includes the following tables:

5.2.1. ug_fcc

  • Stores metadata for FCC diagnostic tasks.

  • Columns: id, ug_task_id, updated, created, updator, creator, threshold_dl, threshold_ul, hubb_id, tier_dl, tier_ul, type.

5.2.2. ug_fcc_speed_result

  • Stores speed diagnostic results.

  • Columns: id, action_id, hubb_id, serial, tier, type, url, start_date, end_date, total_bytes, speed, status, description.

5.2.3. ug_fcc_latency_result

  • Stores latency diagnostic results.

  • Columns: id, action_id, hubb_id, serial, tier, url, start_date, val_avg, val_min, val_max, packets_sent, packets_received, status, description.

5.3. Diagnostic Workflow

The FCC diagnostics feature follows a detailed workflow:

  1. Retrieve active connection BytesSent/BytesReceived parameter values.

  2. Retrieve values again after the specified interval (wan_usage.retrieve.interval).

  3. Calculate current WAN usage: (value - previous value) / (time - time previous) * 0.008.

  4. Compare WAN usage with thresholds for latency or speed diagnostics.

  5. If WAN usage speed is more than the threshold:

    • Save error result in the diagnostic result table.

    • Repeat steps 1-3 after the specified interval (wan_usage.interval) not more than wan_usage.repeat times in total.

  6. If WAN usage is less than the threshold, perform the diagnostic task.

  7. Upon diagnostic completion:

    • Compare diagnostic result with the specified tier and success thresholds (latency.success or speed.success).

    • Save results in the results database table.

  8. Repeat steps 1-7 at the specified interval (fcc.interval) and repeat (fcc.repeat) times.

5.4. Possible Result Descriptions

  • "Unable to find active connection for CPE": Active connection for the CPE is not defined.

  • "Test skipped due to device is offline": UpdateGroup is configured only for online devices, and the current device is offline.

  • "Illegal active connection object name: [PARAMETER_NAME]": Active connection object name is not in the expected format.

  • "Test skipped due to WAN data usage exceeding Threshold: [threshold]Mbps - Actual: [usage]" - p.5

  • "Device didn’t complete diagnostic, diagnostic state is: [DIAGNOSTIC_STATE]" - received state in p.7 not "Completed"

  • "Not all values received from device" - not all parameters received in p.7

  • "Pending task: [TASK_TYPE] is [TASK_STATE]" - some of the tasks in flow is not completed (failed or rejected)

  • "Internal error" — any other issue occurred

5.5. UI design

  • New entries "FCC speed test" and "FCC latency test" are added into "Diagnostics" tasks from "Group Update" tab

  • For "FCC latency test" following fields are present: "Test host", "WAN usage threshold", "HUBB ID" and "Speed tier"

  • For "FCC speed test" following fields are present: "Download URL", "Upload URL", "WAN usage threshold", "HUBB ID" and "Speed tier"

  • Reactivation section is disabled by default with predefined values: "Daily" repeats, "Repeat every" = 1, "Starts on" <next day date> and "Ends" = 6

6. Assumptions

  • Access to network performance metrics is available.

  • Diagnostic thresholds and parameters are correctly configured in the fcc.properties file.

  • Diagnostic tasks are executed asynchronously and can handle intermittent failures gracefully.