HID Proprietary Protocol Sync

This example uses two projects to play the master and slave roles in HID Proprietary Protocol User Guide respectively. They can send messages to each other to demonstrate the basic usage of the protocol:

Master automatically pairs when used for the first time or when a button is triggered, and Slave automatically pairs when used for the first time or when powered on.
Master and Slave automatically reconnect.
Master automatically reports data according to the reporting rate, and the button switches the reporting rate and switches the reporting.
Slave presses the button to issue a command.
LED indications for connection and data transmission.

Requirements

The sample supports the following development kits:

Development Kits
Hardware Platforms	Board Name
RTL87x2G HDK	RTL87x2G EVB

For more requirements, please refer to Quick Start .

Wiring

Please refer to RTL87x2G EVB Interfaces and Modules in Quick Start.

The example will use 3 LEDs to display the relevant status, refer to the table below.

led
Type	Description	LED Name	Pin
link status	Connected on/disconnected off	LED4	P3_0
data transmit	Reversed once every 1000 times of the data transmission from master to slave	LED3	P3_1
slave cmd	Reversed once every time the slave cmd button is pressed	LED2	P1_0

The master example will use 3 buttons, refer to the table below.

master button
Type	Description	Button Name	Pin
pair	trigger pair	KEY5	P1_2
switch report rate	switch report rate	KEY4	P0_6
switch report	switch report	KEY3	P0_2

The slave example will use 1 button, refer to the table below.

master button
Type	Description	Button Name	Pin
slave cmd	Reverse the led of master and slave	KEY5	P1_2

Configurations

Configure macro APP_MSG_COUNT_BLINK_TH to modify the LED flashing frequency when data is transmitted from master to slave.

Configure macro APP_PAIR_TIME to modify the master button pairing time and the slave power-on pairing time.

Building and Downloading

This sample can be found in the SDK folder:

Keil

Project file:

samples\ppt\ppt_sync\proj_master\rtl87x2g\mdk

samples\ppt\ppt_sync\proj_slave\rtl87x2g\mdk

GCC

Project file:

samples\ppt\ppt_sync\proj_master\rtl87x2g\gcc

samples\ppt\ppt_sync\proj_slave\rtl87x2g\gcc

To build and run the sample, follow the steps listed below:

Open project file.
To build the target, follow the steps listed on the Generating App Image in Quick Start.
After a successful compilation, the APP bin app_MP_sdk_xxx.bin will be generated in the directory bin.
To download APP bin into evaluation board, follow the steps listed on the MP Tool Download in Quick Start.
Press reset button on evaluation board and it will start running.

Experimental Verification

After programming the sample to two evaluation boards, use the Debug Analyzer to obtain logs, observe LED status and view the running results.

Testing

When using this example for the first time, there is no bonding information. After pressing the reset button, both ends will automatically enter the pairing state and print the following log.
```
[APP] !**app_sync_start: pair
```
After pairing is successful, the following log will be printed and the link status LED will light up.
```
[APP] !**app_sync_event_cb: paired
```
After the master is connected, data reporting will be turned on by default. At this time, the master and slave will flash the data transmit LED at the same frequency. Press the switch report rate button of the master to switch the master report rate, and it will be seen that the flashing frequency of the data transmit LED of the master and slave has changed. The report rate switching sequence is 125, 250, 500, 1000, 2000, 4000 cycles, and the default is 1000. At the default flashing frequency, the LED flips once every 1s at 1K, once every 0.25s at 4K, once every 8s at 125, and so on.
Press the master’s switch report button once to turn on and off master data reporting. When reporting is turned off, the master and slave’s data transmit LEDs stop flashing.
Press the slave’s slave cmd button once, and the master and slave’s slave cmd LEDs flip at the same time.
Press the master’s pair button once, and the master will re-enter pairing mode. Restart the slave, and the slave will also re-enter pairing mode. After re-pairing is successful, the following log will be printed and the link status LED will light up.
```
[APP] !**app_sync_event_cb: paired
```

Code Overview

The main purpose of this chapter is to help APP developers familiar with the development process. This chapter will be introduced according to the following several parts:

Chapter Source Code Directory introduces the directory path of the project and the source files.
Chapter Initialization introduce the initialization flow.
Chapter State Machine & Event Handler introduce the protocol state machine and event related.
Chapter Data Transmission introduce the data sent by both sides and their format.

Source Code Directory

Project directory: samples\ppt\ppt_sync\proj_xxx
Source code directory: samples\ppt\ppt_sync\src

Source files in the application project are currently categorized into several groups as below.

└── Project: master(slave)
    └── secure_only_app
        ├── Device                   includes startup code
        ├── CMSE Library             Non-secure callable lib
        ├── Lib                      includes all binary symbol files that user application is built on
            ├── ROM_NS.lib
            ├── lowerstack.lib
            ├── rtl87x2g_sdk.lib
            ├── rtl87x2g_io.lib
            └── ppt_sync_master(slave).lib       includes the sync protocol stack lib
        ├── Peripheral               includes all peripheral drivers and module code used by the application
        └── APP                      includes the ble_peripheral user application implementation
            ├── main_ns.c            includes the io, os and platform initialization
            ├── app_task.c           includes app task initialization and main loop
            ├── app_bsp.c            includes the button, led and timer etc. functions
            └── app_sync_master(slave).c         includes sync protocol state machine management and button/led handle

Initialization

When the EVB board boots up and the chip is reset, the main function will be called, which executes the following initialization functions:

int main(void)
{
    /* increase cpu clock to support 4k report rate */
    uint32_t actual_mhz = 0;
    pm_cpu_freq_set(125, &actual_mhz);

    DBG_DIRECT("Non-Secure World: main, clock %dMHz", actual_mhz);

    app_task_init();

    /* Start scheduler. */
    os_sched_start();

    /* Should not reach here as the scheduler is already started. */
    for (; ;)
    {
    }
}

pm_cpu_freq_set() is used to increase the CPU frequency so that 4K high reporting rate can be processed in time.
app_task_init is used to initialize the app task and register the task main function app_main_task .
os_sched_start is used to start the os scheduler. When the scheduler is started, the main function of the app task app_main_task will be scheduled.
app_main_task() performs the initialization of the sync protocol and related content, as shown below.

void app_main_task(void *p_param)
{
    /* This task calls secure side functions. So allocate a secure context for
     * it. */
    //must locate at the first line
    os_alloc_secure_ctx(configMINIMAL_SECURE_STACK_SIZE);

    /* avoid ppt initialization conflict with ble psd procedure */
    os_delay(1000);

    /* init the basic peripheral */
    swd_pin_disable(); // On EVB, led pin reuse the swd pin, so need disable the swd
    led_init();
    app_hw_timer_init();

    /* init sync protocol */
    app_sync_init();
    app_sync_start();

    /* init button after app_sync_start since button may trigger interrupt to change the FSM */
    btn_init(app_handle_btn);

#if DLPS_EN
    /* call pwr_mgr_init last to make sure sync_dlps_init (app_sync_init) execute before DLPS_IORegister (pwr_mgr_init) */
    void pwr_mgr_init(void);
    pwr_mgr_init();
#endif

    while (1)
    {
        /* nothing to do */
        os_delay(1000000);
    }
}

Attention

There are some dependencies between the initialization of io, sync protocol and platform power manager, so pay attention to the order.

app_sync_init will initialize the protocol according to the role and register various callbacks:

Event callback app_sync_event_cb
Receive callback app_sync_receive_msg_cb
Heartbeat callback app_sync_hb_cb

And in sync_msg_send(), the message sending callback app_sync_send_msg_cb will be registered.

State Machine & Event Handler

The main function of the state machine is app_sync_start, which will decide whether to perform pairing or connection based on binding information and button (power-on status) and other information. When pairing and connection are triggered, various events will be generated and processed in app_sync_event_cb. For example, if the pairing fails, app_sync_start will be re-executed. In addition, buttons will also generate events, and app_handle_btn will perform different actions according to the button type, such as re-pairing, sending data, etc. When the master stops reporting data, it will enter the heartbeat low-power state, and the heartbeat callback app_sync_hb_cb will be executed to notify the entry and exit of the heartbeat state.

Data Transmission

The master and slave will send data to each other. When the master turns on reporting, it will continue to send messages according to the reporting rate, and both sides will flash the LED according to the number of messages sent and received. The slave will only send messages to control the LED when the button is pressed.

The definition format is as follows, and users can modify and expand it according to actual needs. The master reporting function is app_report_data, and the data format is as follows.

/* Data send from master to slave */
typedef struct
{
    uint8_t opcode;
    uint32_t pkt_id;
    uint8_t data[0];
} __attribute__((packed)) app_master_pdu_t;

The control function of both LED status sent by slave is app_send_cmd , and the data format is as follows.

/* Data send from slave to master */
typedef struct
{
    uint8_t opcode;
    bool state;
} __attribute__((packed)) app_slave_pdu_t;