Solution: Multimode Keyboard¶
重要
此例程仅存在于特殊版本的SDK中，如有需要请联系Panchip。
1 功能概述¶
此sample为pan108xxb5(64pin芯片)在实体键盘板下的应用
具体支持的feature如下：
通用功能：
按键基础功能
FN+QWERTUASDFGH的组合键功能
2.4G模式（PRF增强型模式）
跳频：在信号质量不好(连续
FREQ_HOP_NOACK_THREHOLD=15个ack未收到)/对码前在8个频点进行跳频对码：上电跳频找到dongle端的频点后，通信互发对端的MAC地址后2字节，之后切换到私有地址进行通信
重传：丢包时会进行重传，以最快速度进行重传直到收到对端回复
ACK：可解析的ACK，具有演示代码
性能：默认上报率1000的情况，近距离可以控制不丢键
BLE模式
蓝牙白名单，分时连接主机设备ABC
配对，保存
连接，重连功能
OTA（未使能）：与mcuboot配合通过NRF工具进行升级
性能：133HZ上报率
性能：兼容性
USB模式
性能：USB2.0 最高速率1000hz
电脑的休眠唤醒（未做）
升级：与mcuboot配合通过USB工具进行升级
2 环境要求¶
board:
pan108xxb5（芯片型号）键盘板USB升级工具（USB升级工具获取：https://docs.panchip.com/pan1080dk-doc/latest/06_dev_tools/pan108x_toolbox_intro.html）
3 编译和烧录¶
例程位置：zephyr\samples_panchip\solutions\multimode_keyboard
使用 ZAL 工具可以对其进行编译、烧录、打开 VS Code 调试等操作。关于 ZAL 工具的详细介绍请参考：Zephyr APP Launcher 工具介绍。
4 演示说明¶
芯片全部擦除还原默认状态，准备好烧录multimode_keyboard_dongle的接收器
键盘供电分为两种模式：
USB供电（开发环境可用）
电池供电（未有实体电源）
4.1 电池供电模式¶
目前硬件点成供电模式未支持，先通过以下USB供电模式进行供电演示功能
4.2 USB供电模式¶
在应用环境下，USB供电后，可通过长按/短按组合键切换3种模式进行键盘数据上报
短按
FN+Q后，切换到USB模式，键盘指示灯显示白色灯效，此时可以通过USB进行键盘按键上报短按
FN+W后，切换到2.4G模式，键盘指示灯显示绿色灯效，如果是没有进行过配对，会显示绿灯快闪，如果已经配对过，会显示绿灯慢闪。此时插入dongle后，进入绿常亮灯效，此时可以通过2.4G进行键盘按键上报，在切换到2.4G通道后，可以通过长按FN+W3秒进入重新配对模式短按
FN+E后，切换到BLE设备A（如PC）模式，键盘指示灯显示蓝色灯效，如果是没有进行过配对，会显示蓝灯快闪，如果已经配对过，会显示蓝灯慢闪。当PC上进行连接（或重连）后，进入蓝灯常亮灯效，此时可以通过BLE进行键盘按键上报，在切换到BLE设备A通道后，可以通过长按FN+E3秒进入重新配对模式短按
FN+R后，切换到BLE设备B（如PC）模式，键盘指示灯显示黄色灯效，如果是没有进行过配对，会显示黄灯快闪，如果已经配对过，会显示黄灯慢闪。当PC上进行连接（或重连）后，进入黄灯常亮灯效，此时可以通过BLE进行键盘按键上报，在切换到BLE设备B通道后，可以通过长按FN+R3秒进入重新配对模式短按
FN+T后，切换到BLE设备C（如PC）模式，键盘指示灯显示青色灯效，如果是没有进行过配对，会显示青灯快闪，如果已经配对过，会显示青灯慢闪。当PC上进行连接（或重连）后，进入青灯常亮灯效，此时可以通过BLE进行键盘按键上报，在切换到BLE设备C通道后，可以通过长按FN+R3秒进入重新配对模式长按
FN+U3秒，进入EMI测试模式，键盘指示灯显示红灯常亮灯效，此时可通过短按FN+F切换测试频点，短按FN+G切换测试模式（载波/发射/接收）短按
FN+A后，打开/关闭RGB灯效短按
FN+S后，增加RGB亮度等级短按
FN+D后，降低RGB亮度等级
5 开发说明¶
5.1 架构说明¶
multimode_keyboard基于zephyr架构，进行多线程编程，线程静态初始化后，根据优先级进行先后初始化，之后各个线程运行至while（1）等待相应的信号量，以此通过控制信号量控制各个线程的调度关系
架构中应用层主要包含
8个线程
电量检测
组包
灯控
低功耗
跳频
对码
RF发包
USB发包
4个中断
TIMER0中断
TIMER1中断
USB中断
PRF中断
2个重要接口
BLE接口（Zephyr API）：FRAME组包后通过调用蓝牙接口进入HOST层进行发包
USB EP3接口（Vendor USB API）：通过USB中断进入进行DFU升级，EMI测试
5.2 线程说明¶
线程定义方式如下，选用静态线程的方式，由于包含多种reboot操作，实际单模式生效可对其他无用线程进行中止操作，线程之间通过信号量进行切换或者挂起
/**
* @brief Statically define and initialize a thread.
*
* The thread may be scheduled for immediate execution or a delayed start.
*
* Thread options are architecture-specific, and can include K_ESSENTIAL,
* K_FP_REGS, and K_SSE_REGS. Multiple options may be specified by separating
* them using "|" (the logical OR operator).
*
* The ID of the thread can be accessed using:
*
* @code extern const k_tid_t <name>; @endcode
*
* @param name Name of the thread.
* @param stack_size Stack size in bytes.
* @param entry Thread entry function.
* @param p1 1st entry point parameter.
* @param p2 2nd entry point parameter.
* @param p3 3rd entry point parameter.
* @param prio Thread priority.
* @param options Thread options.
* @param delay Scheduling delay (in milliseconds), zero for no delay.
*
*
* @internal It has been observed that the x86 compiler by default aligns
* these _static_thread_data structures to 32-byte boundaries, thereby
* wasting space. To work around this, force a 4-byte alignment.
*
*/
#define K_THREAD_DEFINE(name, stack_size, \
entry, p1, p2, p3, \
prio, options, delay) \
K_THREAD_STACK_DEFINE(_k_thread_stack_##name, stack_size); \
struct k_thread _k_thread_obj_##name; \
STRUCT_SECTION_ITERABLE(_static_thread_data, _k_thread_data_##name) = \
Z_THREAD_INITIALIZER(&_k_thread_obj_##name, \
_k_thread_stack_##name, stack_size, \
entry, p1, p2, p3, prio, options, delay, \
NULL, name); \
const k_tid_t name = (k_tid_t)&_k_thread_obj_##name
根据线程定义，定义了如下几个线程
5.2.1 BATTERY线程¶
蓝牙线程，主要处理蓝牙的初始化，广播开启关闭，及蓝牙获取组包数据，
#define BATTERY_THREAD_PRIORITY 7
#define BATTERY_THREAD_STACKSIZE 512
K_THREAD_DEFINE(battery, BATTERY_THREAD_STACKSIZE, thread_battery, NULL, NULL, NULL,
BATTERY_THREAD_PRIORITY, 0, 0);
5.2.2 FRAME线程¶
组包线程，以timer为调度周期（给出信号量）（以上报率1000为例，调度周期1ms）
主要处理组包有关逻辑（ringbuffer的填入），组合按键检测（基础按键组包，DPI模式切换，上报率切换，低电量ADC检测）
#define FRAME_PACK_THREAD_PRIORITY 2
#define FRAME_PACK_THREAD_STACKSIZE 1024
K_THREAD_DEFINE(frame_pack, FRAME_PACK_THREAD_STACKSIZE, thread_frame_pack, NULL, NULL, NULL,
FRAME_PACK_THREAD_PRIORITY, 0, 0);
5.2.3 LED线程¶
灯控线程，通过信号量控制主要灯的状态
#define LED_THREAD_PRIORITY 8
#define LED_THREAD_STACKSIZE 1024
K_THREAD_DEFINE(led, LED_THREAD_STACKSIZE, thread_led, NULL, NULL, NULL,
LED_THREAD_PRIORITY, 0, 0);
5.2.4 PM线程¶
低功耗休眠唤醒线程，控制低功耗休眠唤醒的逻辑
#define LOWPOWER_THREAD_PRIORITY 4
#define LOWPOWER_THREAD_STACKSIZE 256
K_THREAD_DEFINE(lowpower, LOWPOWER_THREAD_STACKSIZE, thread_lowpower, NULL, NULL, NULL,
LOWPOWER_THREAD_PRIORITY, 0, 0);
5.2.5 FREQ_HOP线程¶
跳频线程，初始化对码线程会触发进入，在收到ACK少的时候会触发，通过信号量与PRF线程存在互斥关系
#define FREQ_HOP_THREAD_PRIORITY 2
#define FREQ_HOP_THREAD_STACKSIZE 512
K_THREAD_DEFINE(freq_hop, FREQ_HOP_THREAD_STACKSIZE, thread_freq_hop, NULL, NULL, NULL,
FREQ_HOP_THREAD_PRIORITY, 0, 0);
5.2.6 PRF_PAIR线程¶
配对线程，强制对码/初始化会进入
#define PAIR_THREAD_PRIORITY 2
#define PAIR_THREAD_STACKSIZE 512
K_THREAD_DEFINE(pair, PAIR_THREAD_STACKSIZE, thread_pair, NULL, NULL, NULL,
PAIR_THREAD_PRIORITY, 0, 0);
5.2.7 PRF线程¶
2.4G主线程，会进行重传处理，在重传条件下收到ACK数量低于阈值进入跳频线程
#define PRF_THREAD_PRIORITY 2
#define PRF_THREAD_STACKSIZE 512
K_THREAD_DEFINE(prf, PRF_THREAD_STACKSIZE, thread_prf, NULL, NULL, NULL,
PRF_THREAD_PRIORITY, 0, 0);
5.2.8 USB线程¶
USB线程，USB插入PC时进入，获取组包并且上报
#define USB_THREAD_PRIORITY 2
#define USB_THREAD_STACKSIZE 512
K_THREAD_DEFINE(usb, USB_THREAD_STACKSIZE, thread_usb, NULL, NULL, NULL,
USB_THREAD_PRIORITY, 0, 0);
5.2.9 KEY线程¶
按键扫描与事件处理(基础按键组包，组合按键处理)
#define USB_THREAD_PRIORITY 3
#define USB_THREAD_STACKSIZE 1024
K_THREAD_DEFINE(key, KEY_SCAN_THREAD_STACKSIZE, thread_key, NULL, NULL, NULL,KEY_SCAN_THREAD_PRIORITY, 0, 0);
5.3 RF中断说明¶
5.3.1 RF中断¶
鼠标端为PRF TX端，增强型模式会在TX后自动转入RX, 中断中主要处理信号量sem_prf_isr的给出及ack_lost_cnt的计数
5.3.2 TIMER0中断¶
TIMER0中断产生多线程的控制信号量，并且根据不同上报率切换timer中断间隔
5.3.3 TIMER1中断¶
TIMER1中断用来控制LED灯显示，每一次中断后点亮键盘矩阵中某一列的灯
5.4 主要数据结构说明¶
5.4.1 枚举状态¶
5.4.1.1 配对状态¶
enum prf_pair_stat_t {
prf_pair_start,
prf_pair_comm,
prf_pair_addr,
prf_pair_end,
prf_paired_private,
prf_paired_public,
};
5.4.1.2.连接状态¶
enum ble_connect_stat_t {
ble_disconnect_stat,
ble_connect_stat,
};
5.4.1.3 工作模式¶
enum keyboard_work_mode_t {
keyboard_null_mode,
keyboard_usb_mode,
keyboard_prf_mode,
keyboard_ble_mode,
};
5.4.1.4 2.4G RF状态¶
enum prf_trx_stat_t {
prf_idle_stat,
prf_tx_done_stat,
prf_rx_done_stat,
prf_rx_timeout_stat,
prf_rx_crc_err_stat,
prf_rx_pid_err_stat,
};
5.4.1.5 跳频状态¶
enum prf_freq_hop_stat_t {
freq_hop_disconnect_stat,
freq_hop_connecting_stat,
freq_hop_done_stat,
};
5.4.1.6 USB状态¶
enum usb_plug_mode_t {
usb_plug_in,
usb_plug_out,
};
5.4.1.7 灯状态¶
enum mouse_led_stat_t {
led_unpair_stat,
led_paired_stat,
led_low_batt_stat,
led_prf_connected,
led_key_stat,
};
5.4.1.8 休眠唤醒低功耗状态¶
enum keyboard_low_power_stat_t {
active_stat,
prf_off_stat,
deep_sleep_v1_stat,
deep_sleep_v2_stat,
standby_stat,
};
5.4.2 全局结构¶
5.4.2.1 组包ring_buf（zephyr）¶
/**
* @brief A structure to represent a ring buffer
*/
struct ring_buf {
uint32_t head; /**< Index in buf for the head element */
uint32_t tail; /**< Index in buf for the tail element */
union ring_buf_misc {
struct ring_buf_misc_item_mode {
uint32_t dropped_put_count; /**< Running tally of the
* number of failed put
* attempts.
*/
} item_mode;
struct ring_buf_misc_byte_mode {
uint32_t tmp_tail;
uint32_t tmp_head;
} byte_mode;
} misc;
uint32_t size; /**< Size of buf in 32-bit chunks */
union ring_buf_buffer {
uint32_t *buf32; /**< Memory region for stored entries */
uint8_t *buf8;
} buf;
uint32_t mask; /**< Modulo mask if size is a power of 2 */
struct k_spinlock lock;
};
5.4.2.2 packet格式结构体¶
struct keyboard_pkt_detect_t {
uint8_t key_event;
uint8_t key_value[KEYBOARD_KEY_SIZE];
uint8_t header;
uint8_t sequence;
uint8_t rate_pkt_index;
uint8_t reserved;
};
5.4.2.3 收包计数结构体¶
struct prf_pkt_cnt_t {
uint32_t tx_cnt;
uint32_t rx_cnt;
uint8_t prf_repeat_cnt;
};
5.4.2.4 配对信息结构体¶
struct pair_ctrl_t {
enum prf_pair_stat_t prf_pair_stat;
uint32_t prf_pair_timeout;
uint8_t pair_own_addr[2];
uint8_t pair_peer_addr[2];
bool paired_flag;
};
6 补充说明¶
补充说明当前功耗测试情况，支持中遇到的问题（供参考）及已知仍可能存在的问题
6.1 功耗说明¶
蓝牙目前不关注功耗，确保参考鼠标RF功耗性能一致即可
6.2 已知问题（待测试）¶
No |
已知问题 |
目前状态 |
|---|---|---|
1 |
电脑休眠USB唤醒 |
待更新 |
2 |
对码–未对过码，键盘烧录后未下电或者强制对码，未插入dongle， |
待更新 |
7 RAM/Flash资源使用情况¶
FLASH部分包含蓝牙controller固定资源120K，不包含初始位置开始的60K MCUBOOT程序
Memory region Used Size Region Size %age Used
FLASH: 120936 B 256 KB 46.13%
SRAM: 43936 B 50 KB 85.81%