Skip to content

08_firmware_activation_and_rules_.md

Latest commit

 

History

History
245 lines (177 loc) · 9.19 KB

08_firmware_activation_and_rules_.md

File metadata and controls

245 lines (177 loc) · 9.19 KB

Chapter 8: Firmware Activation and Rules

In the previous chapter, Firmware Management, we explored how xconfwebconfig determines the correct firmware configuration for devices using rules evaluation. Now, in this chapter, we will delve into Firmware Activation and Rules, a critical layer that ensures devices not only receive the correct firmware but also adhere to specific activation rules. These rules ensure that firmware versions are activated based on predefined criteria and contexts.

8.1 Motivation

Firmware activation rules play a vital role in managing the lifecycle of firmware versions. Unlike generic firmware rules that determine which firmware version applies to a device, activation rules focus on when and how a firmware version becomes active for a device. This ensures that devices transition to appropriate firmware versions in a controlled manner.

Central Use Case

Consider a scenario where an organization wants to roll out a new firmware version (e.g., 3.0.0) to all devices of a specific model (MODEL_XYZ). However, before enabling this firmware for all devices, it must meet certain conditions, such as:

  1. Ensuring that the firmware version has been tested with devices in a specific environment (e.g., STAGING).
  2. Validating that the firmware version is compatible with multiple device models or partners.
  3. Blocking the activation of certain firmware versions for specific models or environments.

The Firmware Activation and Rules abstraction addresses these challenges by defining and enforcing activation rules to ensure safe and predictable firmware rollouts.

8.2 Key Concepts

8.2.1 Activation Version

An Activation Version is a structured definition that specifies which firmware versions are allowed to activate for a device based on certain criteria. It includes:

  • Model: The device model the rule applies to.
  • Partner ID: A specific identifier for the device's partner.
  • Regular Expressions: Patterns to match firmware versions.
  • Firmware Versions: A list of explicit firmware versions allowed for activation.

Example Activation Version:

{
    "id": "ACT_001",
    "model": "MODEL_XYZ",
    "partnerId": "partner_123",
    "regularExpressions": ["^3\\.0\\.[0-9]+$"],
    "firmwareVersions": ["3.0.1", "3.0.2"]
}

In this example:

  • The rule applies to devices of model MODEL_XYZ and partner partner_123.
  • Firmware versions matching the pattern 3.0.x or listed explicitly (e.g., 3.0.1) are allowed.

8.2.2 Activation Rule Evaluation

The Activation Rule Evaluation process determines whether a firmware version can be activated for a device by checking:

  1. Device Context: Information such as the device model and partner ID.
  2. Activation Rules: The activation version rules stored in the system.
  3. Matching Logic: The firmware version is validated against both regular expressions and explicit lists in the activation version.

If an activation rule matches the device context, the firmware version is allowed to activate. Otherwise, it is blocked.

8.2.3 Output of Evaluation

The output of the evaluation process is an Activation Result, which includes:

  • Matched Activation Version: The activation rule that matched the device’s context.
  • Firmware Status: Whether the firmware version is allowed to activate or is blocked.
  • Description: A message explaining the outcome.

Example Activation Result:

{
    "matchedActivationVersion": {
        "id": "ACT_001",
        "model": "MODEL_XYZ"
    },
    "status": "ALLOWED",
    "description": "Firmware version 3.0.1 is allowed for activation."
}

8.3 Using Firmware Activation and Rules

Step 1: Defining Activation Versions

Activation versions are typically defined in the database and retrieved dynamically. Below is an example of creating an activation version:

activationVersion := firmware.NewActivationVersion()
activationVersion.ID = "ACT_001"
activationVersion.Model = "MODEL_XYZ"
activationVersion.PartnerId = "partner_123"
activationVersion.RegularExpressions = []string{"^3\\.0\\.[0-9]+$"}
activationVersion.FirmwareVersions = []string{"3.0.1", "3.0.2"}

Explanation:

  • ID: A unique identifier for the activation rule.
  • Model and PartnerId: Define which devices the rule applies to.
  • RegularExpressions: Ensure the firmware version matches a specific pattern.
  • FirmwareVersions: Define specific firmware versions explicitly allowed.

Step 2: Evaluating Activation Rules

To evaluate whether a firmware version can activate for a device, use the following code:

deviceContext := map[string]string{
    "model": "MODEL_XYZ",
    "partnerId": "partner_123",
    "firmwareVersion": "3.0.1",
}

activationResult := evaluateActivationRules(deviceContext, activationVersions)

Explanation:

  • deviceContext: Represents the device’s details.
  • activationVersions: A list of all activation rules (e.g., retrieved from the database).
  • evaluateActivationRules: Processes the context and returns the activation result.

Step 3: Handling Activation Results

The output of the evaluation is handled as follows:

if activationResult.Status == "ALLOWED" {
    fmt.Println("Activation allowed:", activationResult.Description)
} else {
    fmt.Println("Activation blocked:", activationResult.Description)
}

Explanation:

  • If the status is ALLOWED, proceed with the firmware activation.
  • If the status is BLOCKED, inform the device or take corrective action.

8.4 Internal Implementation

Sequence Diagram: Activation Rule Evaluation

The following sequence diagram illustrates the process of evaluating activation rules:

sequenceDiagram
participant Device as Device
participant API as xconfwebconfig API
participant AR as Activation Rules
participant DB as Database

Device->>API: Requests firmware activation
API->>AR: Evaluate activation rules
AR->>DB: Fetch activation versions
DB-->>AR: Return activation versions
AR-->>API: Return activation result
API-->>Device: Respond with activation status
Loading

Code Walkthrough: Evaluation Logic

1. Fetching Activation Versions

Activation versions are fetched from the database using the following function:

func GetActivationVersions() ([]*ActivationVersion, error) {
    return db.GetCachedSimpleDao().GetAllAsList(db.TABLE_ACTIVATION_VERSION, 0)
}

Explanation:

  • Retrieves all activation rules from the ACTIVATION_VERSION table.
  • Returns the rules as a list.

2. Evaluating Rules

The evaluation process matches the device context against the activation rules:

func evaluateActivationRules(ctx map[string]string, activationVersions []*ActivationVersion) *ActivationResult {
    for _, version := range activationVersions {
        if version.Model == ctx["model"] && version.PartnerId == ctx["partnerId"] {
            for _, regex := range version.RegularExpressions {
                if match, _ := regexp.MatchString(regex, ctx["firmwareVersion"]); match {
                    return &ActivationResult{
                        MatchedActivationVersion: version,
                        Status:                   "ALLOWED",
                        Description:              "Firmware version is allowed for activation.",
                    }
                }
            }
            if contains(version.FirmwareVersions, ctx["firmwareVersion"]) {
                return &ActivationResult{
                    MatchedActivationVersion: version,
                    Status:                   "ALLOWED",
                    Description:              "Firmware version is explicitly allowed for activation.",
                }
            }
        }
    }
    return &ActivationResult{
        Status:      "BLOCKED",
        Description: "No matching activation rule found.",
    }
}

Explanation:

  1. Matching Context: Compares the device’s model and partner ID with the activation version.
  2. Regex Check: Validates the firmware version against regular expressions.
  3. Explicit Check: Checks if the firmware version is in the allowed list.
  4. Default Response: If no rules match, the firmware is blocked.

8.5 Best Practices

  1. Use Regex for Flexibility: Use regular expressions to define patterns for firmware versions rather than hardcoding each allowed version.
  2. Validate Rules Early: Ensure that activation rules are validated during creation to avoid runtime errors.
  3. Monitor Rule Changes: Log changes to activation rules to track firmware activation behavior.

Summary

In this chapter, we explored Firmware Activation and Rules in xconfwebconfig. We learned how activation rules ensure that firmware versions are activated in a controlled and context-aware manner. We also implemented the process of defining, evaluating, and handling activation rules. This abstraction enhances the safety and predictability of firmware rollouts.

In the next chapter, we will explore the Rules Engine to understand the underlying system that evaluates complex rules for the application.

Generated by AI Codebase Knowledge Builder