# Device OTA Upgrade Mechanism

## 1. Overview
The OTA (Over-the-Air) upgrade detection mechanism is used to detect device firmware updates in real-time when a user enters the panel mini program or while the panel is running, and guide the user to upgrade based on firmware priority (mandatory/reminder), ensuring the device runs on the optimal version.

> **Tip**: This capability is highly integrated into the [Panel Environment Initialization](./) documentation. Calling this interface during panel mini program initialization will automatically trigger the following OTA upgrade process, requiring no self-implementation by developers.

---

## 2. Logical Flow Chart

```mermaid
graph TD
    Start([Trigger Upgrade Check]) --> Trigger{Trigger Source}
    Trigger -- "Initialization/Enter Panel" --> AdminCheck
    Trigger -- "Received Upgrade Notification Push" --> AdminCheck
    Trigger -- "Device Re-online" --> AdminCheck

    AdminCheck{Is Administrator?} -- No --> End([End])
    AdminCheck -- Yes --> DevFilter{Device Supports OTA and Not Shared}

    DevFilter -- No --> End
    DevFilter -- Yes --> API[Request Cloud Upgrade Information Interface]

    API --> DataCheck{Effective Update Exists?}
    DataCheck -- No --> End
    DataCheck -- Yes --> Priority[Lock Target Item: Mandatory Upgrade > Upgrading > Normal Update]

    Priority --> StatusNode{Firmware Status}

    %% Status: Queuing
    StatusNode -- "Queuing" --> S13_Force{Is Mandatory Upgrade?}
    S13_Force -- No --> End
    S13_Force -- Yes --> Action_Check

    %% Status: Upgrading
    StatusNode -- "Upgrading" --> S25_Check{Mandatory Upgrade OR Uncontrollable during Upgrade?}
    S25_Check -- No --> End
    S25_Check -- Yes --> Action_Check

    %% Status: New Version Available
    StatusNode -- "New Version Available" --> S1_Online{Device Online and Not Check-type Upgrade?}
    S1_Online -- No --> End
    S1_Online -- Yes --> Dialog_Confirm[Pop up Upgrade Confirmation Dialog]

    Dialog_Confirm -- Click Confirm --> Action_Check
    Dialog_Confirm -- Click Cancel --> S1_Cancel{Is Mandatory Upgrade?}
    S1_Cancel -- Yes --> Exit[Exit Mini Program]
    S1_Cancel -- No --> End

    %% Execute Action
    Action_Check{Has Been Checked in This Lifecycle?}
    Action_Check -- Yes --> End
    Action_Check -- No --> OpenOTA[Mark as Checked <br/> Jump to OTA Upgrade Native Page]
```

---

## 3. Upgrade Types

*   **Reminder Upgrade**: Users are actively reminded when entering the device panel, and they can choose whether to upgrade.
*   **Mandatory Upgrade**: Upgrade reminders are actively pushed to App users, who have no choice but to upgrade.
*   **Check-type Upgrade**: Upgrade reminders are not actively pushed to App users; users must manually initiate version detection to see upgrade reminders.

---

## 4. Scenario Descriptions

### Scenario A: Administrator Enters Panel and Finds New Firmware
*   **Behavior**: After the user enters the panel, an upgrade prompt box pops up on the screen, showing the update log.
*   **Logic**:
    1. The interface returns a firmware status of "New Version Available".
    2. Check that the device is currently "Online".
    3. Pop up the upgrade interaction dialog box.
    4. The user jumps after clicking "Upgrade Now", and the dialog box is closed if they click "Cancel" (in non-mandatory cases).

<Image src="/images/panel/panel-ota-tip.en-US.jpg" style={{ width: '256px' }} />

### Scenario B: Mandatory Firmware Upgrade
*   **Behavior**: When the user enters the panel, no reminder dialog appears, and the device panel automatically jumps directly to the device upgrade page.
*   **Logic**:
    1. Identify that the firmware belongs to the "Mandatory Upgrade" type.
    2. Jump directly to the OTA upgrade native page.

<Image src="/images/panel/panel-ota-detail.en-US.jpg" style={{ width: '256px' }} />

### Scenario C: Device Starts Upgrading while Panel is Running (Triggered by Push)
*   **Behavior**: While the user is operating the device, they suddenly receive a "Device is upgrading" prompt.
*   **Logic**:
    1. The framework receives the upgrade notification push sent from the cloud.
    2. Trigger the upgrade check process.
    3. If it is judged that the firmware is upgrading and uncontrollable, an upgrade notification pop-up will appear to guide the user to check the progress and prevent conflicting operations during the upgrade.

<Image src="/images/panel/panel-ota-tip.en-US.jpg" style={{ width: '256px' }} />

### Scenario D: Shared Device or Regular Family Member
*   **Behavior**: No OTA-related pop-ups or logic are triggered at all.
*   **Logic**:
    1. The framework verifies the current user permissions; if not an "Administrator", the process is terminated.
    2. Verify device properties; if it is a "Shared Device", the process is terminated.

---

## 5. Precautions
1.  **Anti-shake Mechanism**: The upgrade check function has a certain anti-shake time to ensure that only one effective request is executed when triggered multiple times in a short period (such as simultaneous initialization and receiving a push).
2.  **Lifecycle Marking**: An "Already Checked" status is maintained internally to ensure that the mandatory update detection will not repeatedly interfere with the user during a single running lifecycle of the mini program.
3.  **Exit Logic**: When handling mandatory upgrades, the framework strictly executes the exit mechanism. Developers should ensure not to break this loop when fine-tuning logic to avoid business anomalies caused by inconsistent firmware versions.
4.  **Functional Standardization and Closure**: This OTA mechanism is a unified standard capability built into the basic library, aiming to ensure that all panel applications remain highly consistent in device firmware security and user upgrade experience. To guarantee the rigor of the core chain, **currently, customized interfaces or configuration items are not open to developers**. Please conduct business evaluations based on the standardized behavior provided by the framework.