杰理JL701N双屏demo介绍

📎 原始文档：https://www.kdocs.cn/l/crv53cE0bZNR 杰理JL701N双屏demo介绍

补丁下载：701N_双屏补丁v1.0.zip

第1章发布补丁与环境搭建

1.1 v1.0补丁内容

本次发布的补丁中包含13个改动文件，用户只需要将补丁包内的文件替换到自己的sdk中即可。其中每个文件相较于原SDK的改动内容已经在第3章中介绍
文件包含：
C文件：
新增：ui_action_dl_functions.c ui_action_dl_lcd1.c ui_action_dl_lcd2.c ui_action_dl_lefteye.c ui_action_dl_righteye.c
改动：power_on.c lcd_drive.c lcd_ui_api.c app_common.c
H文件：ui_api.h ui_style.h board_701n_demo_cfg.h
编译文件：Makefile

1.2 使用补丁后的环境搭建指南

本小节指引客户在加入双屏补丁后快速搭建双屏开发环境。
0.双屏V1.0补丁包含了board_701n_demo_cfg.h公板板级配置文件，其中包含了新增的双屏功能宏定义，如果用户用的是公板sdk，直接将补丁中的板级配置文件替换到自己的SDK即可，如果是别的版本，可以手动将补丁板级配置文件中的内容添加到自己的板级配置中。其余改动文件相较于原公板SDK的改动点在第四章中有详细介绍，如果客户是公板sdk直接将补丁文件替换到自己的sdk即可，如果是别的版本可以参考第四章的改动将双屏内容添加到相应位置。
当前版本在无休眠状态下运行，不考虑休眠唤醒。
1.首先，修改ui_style.h中用于双屏显示的页面ID，ID_WINDOW_LCD的具体值取决于用户使用哪个UI工程生成的pageid。用户可以选择两种工程生成资源的方式：1.在“模式界面”的UI工程中添加两个页面存放两个屏幕的动画切图素材，该方法不需要考虑新增工程，直接在原工程上进行修改即可；2.用户可以自己参照原UI工程的格式新建一个，专门存放双屏相关的所有UI素材。v1.0补丁用的是方法1，ui_style.h中的#include "ui/style_DUAL_LCD.h"在本版本中没有使用，用户可以删除该声明。
2.上述两种新增UI的方式各有优势：方法1对于原UI工程框架而言改动小，添加好布局并编译资源后可以直接烧录代码，且遇到空间不足需要裁剪资源的时候，可以逐步裁剪原工程的页面，并在SDK编译阶段根据报错信息去屏蔽相关功能；方法2完全新建UI工程，需要用户配置好ui工程的设置，并修改download.bat加载的资源，以及需要完全修改原SDK使用到的所有页面ID以及控件ID，起步很麻烦，但完全修改好后双屏开发的UI资源环境更简洁明了。
3.接下来详细介绍方法1的操作流程：
用户可以在自己的sdk中的模式界面的工程资源中添加新的资源。
在ui tool中完成布局后，点击编译资源即可（注意事项：如果编译报错“图片分辨率必须为16倍数”将图片素材的尺寸修改为16的倍数即可，图中的大图素材尺寸是448x448）
资源编译完成后，来到ui_style.h，修改页面ID映射
接下来修改ui_action_dl_lefteye/righteye.c的图片控件注册，本版本以及将帧同步、当前控件是否显示等逻辑封装为接口，用户如果新增了一组图片素材，复制粘贴一份文件中的控件逻辑即可，仅需要修改图片控件的ID。来到ui_api.h 添加新图片素材的索引以及控件ID
选择一个地方开始双屏显示，v1.0选择在开机页面结束后就开始显示双屏内容。具体的时序逻辑如下：
开机->app_poweron_task注册PB1 IO中断->开机页面结束后，调用power_on_unint显示第一个页面并调用app_task_switch_to(APP_BT_TASK)->按下KEY0（触发PB1中断）进行功能切换，创建双屏刷新定时器，定时回调关联到bt_task上下文，定时器到期，systimer线程发事件给bt_task，双屏动画刷新回调在bt_task的上下文执行->触发非UI线程的渲染需求，进行阻塞等待
编译时报错，图片资源太大编译失败，空间不足怎么办？可以修改watch/download.bat的下载对象
删减模式界面UI工程的页面，建议是每删10个页面，编译一次SDK，根据报错去屏蔽失去控件/页面ID定义的代码。
加入新的资源时，如果切图格式为png，格式可以选择rgb565，减少图片素材的位深也可以减小资源占用空间；jpg图片则选择默认的jpeg即可。

第2章 V1.0双屏显示框架概述

2.1 DEMO描述

本双屏框架基于701n_demo SDK开发，实现多组双眼动画同步播放效果，适用于不考虑触摸只关注显示效果的应用场景。

2.2 V1.0核心特性

双屏同步渲染：支持两个SPI LCD的同步显示
同步帧管理：统一的动画帧控制，确保双眼当前显示帧一致
显示模式：支持单屏1、单屏2、同步、异步四种显示模式
动画模式：支持单组表情、自动切换、组合表情三种表情动画播放方式
双屏接口：目前提供了3种核心接口 3种便携接口 3种状态查询接口，用户可根据测试需要
UI框架兼容：v1.0版本完全基于UI应用层进行修改，与杰理UI框架完全兼容

2.3 技术规格

显示分辨率：支持240x240至454x454像素的素材
刷新间隔：每帧画面间隔最短5ms（测试素材448x448，经测试验证＞30帧）
动画帧数：支持每组动画有不同的帧数，自动管理每组动画的帧数（素材的帧数量取决于资源空间够不够）
表情组数：支持多组不同动画数量切换（动画组数取决于资源空间够不够）

第3章技术原理

该部分主要介绍双屏v1.0的软硬件设计思路。

3.1硬件架构

双屏v1.0的硬件设计基于701n公板进行拓展。
701n公板使用sh8601 QSPI LCD。双屏v1.0采用两块sh8601进行开发。两个LCD共用QSPI时钟数据线，CS、EN脚分离，CS是控制双屏显示的核心。当前版本不考虑TE的帧同步。在硬件接线上，由于共用时钟数据线，请增强对应的时钟数据IO口的输出强度，并确保两个屏幕与主板的连接足够稳定，否则会出现信号质量下降导致的花屏、画面撕裂等情况。以及在v1.0中可以两个屏幕都不接TE脚，或是
在设置中将TE脚配置为NO_CONFIG_PORT，当前没有设计双屏TE的处理流程，如果两个屏幕共用TE脚会因为两个TE信号影响屏幕的数据时序导致显示不正常。
屏幕时钟线CLK-PA7；数据线SD0-PA8，SD1-PA9，SD2-PA10，SD3-PA11，芯片IO不建议映射其他IO，建议固定使用这几个（PA7、PA8、PA9、PA10、PA11）。

3.2软件设计框架

双屏v1.0以最小侵略性改动去实现两个屏幕的显示以及刷新逻辑。在渲染和推屏的流程上是和701公板sdk一致的（对于一个屏幕而言）

3.2.1杰理UI框架的渲染推屏流程

701N杰理UI框架可以参考资料包中的文档进行了解。
应用层 UI_SHOW_WINDOW宏接口 ui_api.h
↓
框架层 ui_show_main, ui_task消息处理 lcd_ui_api.c ui.h
↓
平台层 ui_platform.c 执行IMB渲染任务链 ui_platform.c
↓
IMD推屏在701nSDK默认状态下，IMB合成完毕后自动触发IMD推屏

3.2.2双屏v1.0的动画刷新逻辑流程介绍

双屏v1.0主要关注两个屏幕显示不同的内容，尤其是两个屏幕都有动态刷新的需求时，例如左眼和右眼为一组的动画。现版本以短间隔定时器为核心，配合双屏同步帧管理在定时回调中调用UI_SHOW_WINDOW去刷新页面，通过杰理UI的图片控件接口去获取当前动画组的帧数、根据当前帧显示图片列表中的对应切图、根据状态量决定哪一组动画显示。
（1）创建两个page专门作为双屏动态素材页面。

定时器回调中推送双屏各一帧的画面
与701nSDK编程风格一致的ui_action_LCD1/LCD2.c 在里面注册每一个图片控件的处理逻辑。
同步机制原理利用到了杰理UI框架内置的渲染同步机制（后面会详细介绍）

第4章主要数据结构以及接口介绍

本章主要介绍基于701nSDK修改及新增的双屏框架代码，介绍当前版本具有的功能以及具体的逻辑流程。

4.1文件修改介绍

4.1.1新增文件：

ui_action_dl_functions.c：双屏逻辑主实现
ui_action_lefteye：左眼图片控件注册
ui_action_righteye：右眼图片控件注册
ui_action_lcd1: 预留的LCD1单屏显示页面
ui_action_lcd2: 预留的LCD2单屏显示页面

4.1.2改动文件：

power_on.c:

开机流程集成，替换原逻辑中的显示表盘为分别在LCD1和LCD2显示两个不一样的静态页面。同时在app_poweron_task中注册KEY0（home键，公板IO为PB1）的中断回调，回调处理后续的按键测试逻辑

lcd_drive.c:

提高IO驱动强度，在cs和en控制逻辑中添加双屏控制

lcd_ui_api.c:

关闭卡片管理初始化，当前版本用不上。

app_common.c:

拦截app_common_key_msg_deal中对于KEY_UI_HOME的处理。

ui_api.h:

添加双屏接口声明

ui_style.h:

声明页面id

board_701n_demo_cfg.h:

IO以及控制宏声明
当前版本在无休眠状态下运行，不考虑休眠唤醒。

4.2数据结构介绍

4.2.1当前显示模式选择以及推送的目标屏幕选择

4.2.2动画素材组以及显示控制

4.2.3定时刷新模式

4.2.4播放模式枚举

4.2.5播放状态控制枚举

4.2.6播放模式配置联合体

4.2.7双屏主实现逻辑的全局变量以及双眼动画管理系统

4.3双屏V1.0接口介绍

本小节介绍v1.0的接口使用

4.3.1基础双屏模式接口

4.3.2眼睛动画管理系统

advance_animation_frame是帧同步的关键，由于本质上两个LCD显示页面是有前后顺序的，因此除了尽可能减少两个LCD推屏的时间间隔外，需要统一管理两个页面的帧数才能实现在同一时间间隔内两个屏幕显示的动画是同一帧。同时在其中集成了单表情、组合表情、自动切换三种播放模式的逻辑，根据外部接口设置的配置信息去显示。
dual_eye_animation_callback定时回调是实现双屏推送的核心，其中提供了连续渲染以及串行渲染两个模式以供用户直观的感受两种显示方式的区别。连续渲染模式在同一个时间间隔内完成“选择推屏LCD1，在LCD1显示页面；选择推屏LCD2，在LCD2显示页面”两件事，而串行模式则是一个时间间隔内推完屏幕1再推屏幕2。后续的方案都建议使用连续渲染，连续渲染模式下，动画的帧数更好管理且同步效果好，不会出现串行模式中明显的双眼动画不同步的观感。完成推屏后调用advance_animation_frame进行帧管理。

4.3.3 V1.0外部调用接口

4.3.3.1 核心接口

dual_eye_set_play_mode：
该接口设置播放模式和参数
dual_eye_start_animation：
该接口为启动动画接口。每次调用都会先清楚原有的定时器，设置定时刷新模式以及播放状态，创建双屏动画刷新定时器
dual_eye_control_animation:
该接口负责控制动画的播放状态

4.3.3.2 便捷接口

dual_eye_start_single_mode:
单一表情模式的启动接口。输入需要显示的表情组以及刷新模式
dual_eye_start_combo_mode:
组合表情模式的启动接口。输入需要组合的表情索引数组，组合表情数量，刷新模式
dual_eye_start_auto_switch_mode:
自动切换模式的启动接口。输入自动切换的起始表情组以及结束表情组，刷新模式。从输入的起始表情开始自动按顺序切换至结束的表情组。

4.3.3.3 状态查询接口

dual_eye_get_play_mode:
获取当前播放模式：单一、组合、自动
is_expression_group_active:
判断指定表情组是否为当前活动动画组。单一：返回当前表情组；组合：检查输入的表情组是否在组合表中，是返回1否返回0；自动：输入的表情组是否在自动切换范围内
dual_eye_print_status:
打印播放状态信息

4.3.3.4 动画页面调用接口

get_current_expression_group:
获取当前表情组
get_current_animation_frame:
获取当前动画帧
get_expression_group_display_status:
获取当前播放模式下该组表情控件的显示状态
eyes_anim_show_with_frame:
在ui_action_dl_lefteye/righteye.c中调用

4.4按键测试功能

当前版本提供了8个测试逻辑，每按一次KEY0就会切换一次测试功能，用户可以根据需要组合自己需要的测试功能组。现版本直接为KEY0的IO申请了中断回调，因此需要增加防抖防止短时间多次触发回调，同时请注意不要在中断中处理过于复杂的逻辑，最好以消息传递的机制管理功能。
用户可以根据自己的按键数量注册不同的回调，请注意在原SDK逻辑中接管相应逻辑，避免走到原SDK的流程。

第5章双屏V1.0使用指南

请在板级配置文件中开启宏进行功能区分，以便开发过程中裁剪原功能代码以及管理双屏框架的代码。
硬件连接方面，参考前文提及的即可，确保两个屏幕与主板连接的稳定性。
由于共用时钟数据线，两个屏幕在开机初始化时是一起的，具体LCD的配置按照原SDK的配置流程即可。
双屏显示的起点在power_on_unint()，本版本在开机页面结束后向两个屏幕分别推送了不同的静态画面，作为非动画状态下的开发参考。用户可以根据需要选择开机后显示的首页。

5.1.在双屏框架中新增动画组

5.1.1添加UI资源

用户在工程中新建好两个用于显示动画素材的页面后，每一个新的切图组都创建一个图片控件，设置其默认显示状态以及在图片列表中加入需要的切图

5.1.2确认ui_style.h中页面的window_id映射正确

如果有在工程中删减了页面，page_id会变，注意及时修改。建议直接使用开机后面的页面，这样后续删减原工程不需要频繁改动page_id。删减页面后原有的page_id以及控件id没有了，请在编译阶段根据报错去屏蔽原SDK的代码。

5.1.3添加素材组成员

5.1.4在ui_action_dl_lefteye/righteye.c中注册控件事件

5.2.双屏v1.0注意事项

5.2.1同步机制的实现

定时回调运行在非UI task的上下文，回调中调用UI_SHOW_WINDOW触发了杰理UI框架中的非UI线程调用时进行阻塞等待的逻辑，但在渲染压力大以及定时间隔非常小的情况下还是存在画面撕裂的风险，因此当前版本不建议显示过于复杂以及尺寸过大的图片，定时间隔不建议低于5ms

5.2.2杰理定时器接口

杰理701提供了两种定时器接口

定时器类型	接口	优先级	同步/异步	执行上下文	低功耗
强节拍usr_timer	Usr_timer	1	异步	硬件定时器中断	无法进入
弱节拍user_timer	Usr_timer	0	异步	硬件定时器中断	低功耗会忽略节拍
normal节拍sys_timer	Sys_timer	无	同步	Systimer线程->add任务	支持低功耗

5.2.3资源裁剪

由于当前采用的是切图，占用很多资源空间。客户可以自行新建一个工程存放双屏UI页面，然后在watch/download.bat脚本中修改下载到主板的资源。如果在模式界面进行删减，则需要注意杰理UI工具编译后生成的新映射表，原SDK中应用到被删除的控件/页面ID时都需要根据报错去屏蔽。

5.2.4待优化内容

IO中断回调：IO中断回调设计原则力求简洁，仅在回调中发送消息，具体逻辑交给具体的task处理更好
双屏专门的task：与IO中断回调配套，专门处理双屏的逻辑（例如，创建删除双屏定时器、切换测试功能等等）
按键响应：v1.0使用IO中断去替代原有的按键消息处理的原因是在定时器刷新的过程中UItask在频繁工作，原有的按键消息不能得到及时响应。
双屏刷新的触发方式：共用同一路spi方案下的双屏显示核心在于cs切换的时机，定时器是一种固定的切换cs方式，后续可以优化为具体的在有双屏显示动画等需求的时候，在推完一帧完整画面的时机进行切换cs。

第六章 FAQ

第七章改动日志

本章记录双屏demo的改动日志，指引客户更新

修改内容：将eyes_anim_show_with_frame接口中调用的ui_pic_show_image_by_id更改为ui_pic_set_image_index。输入参数中加入struct ui_pic*pic
修改原因：一般而言，带by_id后缀的接口均带重绘，故不能在onchange事件中直接调用，否则会触发刷新，刷新又触发onchange，从而在此触发onchange中的redraw，陷入死循环。双屏demo的刷新触发依赖定时器，因此再onchange中不使用带redraw的接口。