Skip to content

01_project_overview_and_api_documentation_.md

Latest commit

 

History

History
207 lines (158 loc) · 6.84 KB

01_project_overview_and_api_documentation_.md

File metadata and controls

207 lines (158 loc) · 6.84 KB

Chapter 1: Project Overview and API Documentation

Welcome to the first chapter of the xconfwebconfig tutorial! In this chapter, we will explore the purpose, architecture, setup instructions, and API details for the xconfwebconfig project. By the end of this chapter, you will have a solid understanding of what this project does, the tools it uses, and how to interact with its APIs.

1.1 What is xconfwebconfig?

xconfwebconfig is a backend application designed to manage firmware and configuration settings for set-top boxes (STBs). It acts as the central system responsible for determining which firmware version an STB should use and provides the necessary information to the devices. However, it does not handle the actual firmware download or update process.

Key Features:

  • Firmware Management: Determines the correct firmware version for STBs based on various inputs (e.g., model, environment, etc.).
  • Device Configuration Management (DCM): Provides configuration settings for remote devices like STBs and DVRs.
  • Feature Control: Enables or disables specific features on devices based on predefined rules.

1.2 Architecture Overview

The project is built using the following core components and tools:

  • Language: Golang
  • Web Framework: gorilla/mux
  • Database: Cassandra DB

This architecture ensures high scalability, efficient data handling, and robust performance, which are critical for managing large populations of STBs.

High-Level Architecture:

flowchart TD
    A[STB Device] -->|Requests Firmware/Settings| B[xconfwebconfig]
    B -->|Fetches Data| C[Cassandra DB]
    C -->|Returns Data| B
    B -->|Responds with JSON| A
Loading
  1. STB Device: Sends HTTP requests to xconfwebconfig with details like MAC address, model, firmware version, etc.
  2. xconfwebconfig: Processes the request, applies rules, and fetches data from the Cassandra database.
  3. Cassandra DB: Stores all the necessary firmware, configuration, and rule data.

1.3 Setting Up xconfwebconfig

Follow these steps to get the xconfwebconfig application up and running.

Step 1: Set up Cassandra DB

  1. Install and run Cassandra DB.
  2. Use the db_init.cql file (located in the db folder) to create the necessary database schema.

Step 2: Configure the Application

  • Copy the config/sample_xconfwebconfig.conf file to a new location and edit it to override specific environment properties.

Step 3: Build the Application

Run the following commands to build the binary:

cd .../xconfwebconfig
make

Step 4: Run the Application

Before running the application, export the required environment variables:

export SAT_CLIENT_ID='xxxxxx'
export SAT_CLIENT_SECRET='yyyyyy'
export SECURITY_TOKEN_KEY='zzzzzz'

Then, start the application:

mkdir -p /app/logs/xconfwebconfig
cd .../xconfwebconfig
bin/xconfwebconfig-linux-amd64 -f config/sample_xconfwebconfig.conf

1.4 API Documentation

The xconfwebconfig application exposes several APIs that allow STBs and other systems to interact with it. Below, we provide an overview of the primary APIs and their usage.

1.4.1 XConf Primary API

Endpoints:

PATH METHOD QUERY PARAMETERS DESCRIPTION
/xconf/swu/{applicationType} GET eStbMac, ipAddress, env, model, firmwareVersion, partnerId, etc. Returns firmware information for the STB.
/xconf/swu/bse GET ipAddress Returns BSE configuration.
/xconf/{applicationType}/runningFirmwareVersion/info GET mac Returns activation and minimum firmware details.
/estbfirmware/checkMinimumFirmware GET mac Checks if the device has the minimum firmware version.

Example Request:

curl --location --request GET 'https://<xconf-path>/xconf/swu/stb?eStbMac=AA:AA:AA:AA:AA:AA&env=DEV&model=TEST_MODEL'

Example Response:

{
    "firmwareDownloadProtocol": "http",
    "firmwareFilename": "FIRMWARE-NAME.bin",
    "firmwareLocation": "http://example-url.com/cgi-bin/x1-sign-redirect.pl",
    "firmwareVersion": "1.0.0",
    "rebootImmediately": true
}

1.4.2 Device Configuration Manager (DCM)

Endpoints:

PATH METHOD QUERY PARAMETERS DESCRIPTION
/loguploader/getSettings/{applicationType} GET estbMacAddress, ipAddress, env, etc. Returns configuration settings for the STB.
/loguploader/getTelemetryProfiles/{applicationType} GET Same as above Returns Telemetry 2.0 profiles.

Example Request:

curl --location --request GET 'https://<xconf-path>/loguploader/getSettings/stb?estbMacAddress=AA:AA:AA:AA:AA:AA'

Example Response:

{
  "urn:settings:CheckSchedule:cron": "19 7 * * *",
  "urn:settings:LogUploadSettings:UploadRepository:URL": "https://upload-repository-url.com",
  "urn:settings:TelemetryProfile": {
    "id": "c34518e8-0af5-4524-b96d-c2efb1904458",
    "schedule": "*/15 * * * *"
  }
}

1.4.3 RDK Feature Control

Endpoints:

PATH METHOD QUERY PARAMETERS DESCRIPTION
/featureControl/getSettings/{applicationType} GET estbMacAddress, ipAddress, env, etc. Returns enabled/disabled features for the device.

Example Request:

curl --location --request GET 'https://<xconf-path>/featureControl/getSettings?estbMacAddress=AA:AA:AA:AA:AA:AA' \
--header 'Accept: application/json'

Example Response:

{
    "featureControl": {
        "features": [
            {
                "name": "TEST_FEATURE",
                "enable": true
            }
        ]
    }
}

1.5 Rule Structure

Overview:

Rules are used to apply specific logic for firmware, configuration, telemetry, and feature management. There are six different rule types:

  • FirmwareRule
  • DCM Rule
  • TelemetryRule
  • TelemetryTwoRule
  • SettingRule
  • FeatureRule

Each rule consists of conditions, which are applied to determine the appropriate response.

Example Rule:

{
    "negated": false,
    "condition": {
        "freeArg": {
            "type": "STRING",
            "name": "model"
        },
        "operation": "IS",
        "fixedArg": {
            "value": "TEST_MODEL"
        }
    }
}

Summary

In this chapter, we explored the xconfwebconfig project, its architecture, setup process, and API documentation. You learned how xconfwebconfig enables firmware and configuration management for STBs and how to interact with its APIs.

Next, we’ll dive deeper into how the HTTP server and routing are implemented in the project. Continue to HTTP Server and Routing.

Generated by AI Codebase Knowledge Builder