Dashboard Card SDK Usage

Revision History

1. Overview

This document describes how to integrate the pages, navigation callbacks, resource extension capabilities, and Aqara Spec data notification and control capabilities provided by the Dashboard Card SDK based on the host project's MainActivity, initHome(), and host callback and strategy implementations.

2. Prerequisites

1. Complete the preparation work
2. Complete the environment setup
3. Complete the integration of the Dashboard Card SDK

3. Usage

3.1 Open the Dashboard Card Page

The host entry page first determines the current device form, then initializes the Home module, and finally loads the home homepage HomeMainFragment:

class MainActivity : BaseActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // 1. Set phone / tablet mode
        LumiRouterManager.instance.isTablet =
            resources.configuration.orientation == Configuration.ORIENTATION_LANDSCAPE

        // 2. Initialize the home capability
        initHome()

        // 3. Load the home homepage
        startHome()
    }

    open fun startHome() {
        loadRootFragment(R.id.fl_container, HomeMainFragment())
    }
}

Key Parameters

To navigate to other pages such as the Service Square or card list, reuse the host implementation pattern of ARouter.build(...).withString(PATH_KEY, ...).navigation() and replace the target path.

3.2 Dashboard Navigation Callback

3.2.1 Callback Overview

Capabilities such as card click handling, page navigation, offline handling, and web page opening are exposed to the host through IHomeConfigurationCallback.

Integration steps:

1. The host implements a callback class, for example HomeCallBack
2. The callback class implements IHomeConfigurationCallback
3. The callback is exposed to the dashboard module through ARouter

IHomeConfigurationCallback is the unified navigation interface exposed by the dashboard module to the host. Card clicks, page transitions, offline handling, web page opening, and theme changes are eventually passed back through this interface.

3.2.2 IHomeConfigurationCallback Interface

The key characteristics of this interface are:

1. It inherits from IProvider and is discovered through ARouter
2. Most business entities are passed through as Any, and the host must cast them to the actual types
3. The dashboard module calls this interface through a unified routing layer without directly depending on host business pages

Common methods and parameter conventions are as follows:

Additional notes:

1. The dashboard module determines which callback method to invoke based on the card type
2. For example, device cards call gotoDeviceHomePage(...) and scene cards call gotoSceneHomePage(...)
3. The host must correctly recognize the real type behind each Any parameter in order to retrieve the passed business data

3.2.3 Integration Requirements

1. Review the host's existing pages and confirm the paths and parameters for device detail, home management, scenes, automations, and web containers
2. Implement the actual navigation logic in the IHomeConfigurationCallback implementation using ARouter or the host routing system
3. If the project only displays dashboard content, implement device, scene, and web navigation first, and keep the remaining callbacks as placeholders

3.3 IALinkCallBack Interface

3.3.1 Interface Responsibilities

The Dashboard Card SDK connects to the host device link layer through IALinkCallBack to handle Aqara Spec related data notifications and control capabilities. The host implements the following method types in this interface:

1. Push callback methods for receiving real-time trait change notifications
2. Data read proxy methods for reading current values by device, function, or trait
3. trait write methods for modifying trait property values
4. Command dispatch methods for executing device commands that are independent of trait write

3.3.2 Key Methods

3.3.3 Related Entities

IALinkCallBack uses the following core entities:

Additional notes:

1. TraitPushEntity represents a device report result and is used in passive notification flows
2. Trait uses deviceId, path, and value to describe the target device, target capability, and current value
3. AqaraSpecConfigCmdEntity represents a command description and is used in command dispatch flows

3.3.4 Integration Requirements

1. Ensure that IALinkCallBack is registered and invoked through the unified device link layer
2. Use onTraitPush(...) as the real-time update entry for device reports and passive refreshes
3. Reuse the host's existing device cache, device center, or query APIs for read proxy methods
4. Route trait write methods through the host's existing write path so permission checks, throttling, logging, and retries stay consistent
5. Route command dispatch methods through an independent command control path and keep the implementation separate from trait write
6. When trait changes are frequent, add deduplication, throttling, or device-level merged refresh logic to reduce UI jitter and repeated rendering

3.3.5 Usage Notes

1. IALinkCallBack is the core interface for integrating Aqara Spec data notifications and control capabilities in the dashboard module
2. Push callbacks, data reads, trait write, and command dispatch are planned uniformly by the host and implemented as separate paths
3. trait write is used for property updates, while command dispatch is used for independent device commands, and they are not the same control mode
4. If this interface is not implemented correctly, card refreshes fail, first-screen status becomes inaccurate, or control behavior becomes inconsistent

3.4 Dashboard Feature Switches

3.4.1 IPanelPermissionStrategy Overview

Whether dashboard capabilities are shown, clickable, or editable is controlled through IPanelPermissionStrategy.

This interface controls which features are visible or available on the Home Configuration pages, and the host injects its own strategy during initialization.

LMHomeManager.getInstance().setPanelPermissionStrategy(object : IPanelPermissionStrategy {
    override fun supportVoice() = false
    override fun supportAddDeviceSceneAutomation() = true
    override fun supportCardClick() = false
    override fun supportEditCard() = true
    override fun supportSwitchHome() = true
    override fun supportStatistics() = true
    override fun supportThemePanel() = false
    override fun supportLAN() = true
    override fun supportCardType() = getSupportCardType()
})

3.4.2 Common Strategy Items

3.4.3 Usage Requirements

If the project only displays dashboard content, confirm the following switches first:

1. supportCardClick() decides whether cards can open details or trigger navigation
2. supportEditCard() decides whether users can edit cards
3. supportSwitchHome() decides whether switching across homes is allowed
4. supportCardType() decides which card types can be displayed on the dashboard

If the goal is display only with no navigation, set supportCardClick() to false and keep the editing and home switching switches that the project needs.

3.5 Resource Extension

3.5.1 Local Resource Extension (Optional)

To override default skins, images, or copywriting, place custom resources in the Demo resources or assets directories and inject them through extension points such as ThemeStyle.getInstance().getBaseThemePack() or ResourcesWrapper.

3.5.2 Remote Resources (Optional)

The Dashboard Card SDK supports delivering card skins, copywriting, and related resources through remote configuration. The current version is maintained by the internal configuration center. Contact business support for external access.

The examples above are based on the Demo structure of the host project. Trim them based on business scope and keep the onCreate -> initHome -> startHome call chain to complete integration of the home homepage and core dashboard card capabilities.