# lua显示组件

**Repository Path**: oneos-ability/lua-display-component

## Basic Information

- **Project Name**: lua显示组件
- **Description**: lua显示组件
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2024-10-21
- **Last Updated**: 2025-02-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LuaOne #

## 1. 功能介绍

​	LuaOne软件包是嵌入式脚本语言Lua基于OneOS操作系统的实现，由于作者的水平有限，没有基于shell组件将Lua的REPL交互模式完全实现，而是以shell注册命令的方式实现了Lua的单行执行。同时，该组件支持脚本的运行态，即开机自动检测**init.lua**进行初始化操作，并检索**main.lua**循环执行。(这需要设备支持文件系统，同时提供标准posix文件操作接口)。此外，我还同时封装了函数注册接口，可以将C函数代码很方便的注册到Lua运行环境中，进而实现不用重新烧写固件，直接用脚本即可对设备进行编程的效果。

## 2. 使用方法

​	将**LuaOne**文件夹放入**thirdparty**文件夹下，运行OneOSCube配置工具，选择**Thirdparty->LuaOne**即可看到如下配置界面：

![image-20211204153218973](png/image-20211204153218973.png)

| 选项                           | 含义                                                         |
| ------------------------------ | ------------------------------------------------------------ |
| Enable Lua                     | 是否使用该软件包                                             |
| Lua buffer size                | Lua脚本缓冲区大小，表示最大可支持运行的脚本字符数量          |
| Max function number of one reg | Lua函数注册类中最大支持的函数数量                            |
| Max reg number                 | Lua解释器支持的最大函数注册类的数量                          |
| Lua support filesystem         | Lua支持文件系统，打开后会启用Lua运行态，请确保系统支持文件系统 |
| Stack size of Lua              | Lua线程的堆栈大小                                            |
| Default path of *.lua          | Lua脚本在设备中的存放路径例如填写/spiflash/则系统会寻找/spiflash/main.lua[^1] |

[^1]:此项配置已经在后续版本中移除，笔者发现Kconfig无法生成字符串类型的配置项，此宏定义已经移动至luarun.h中修改SCRIPTS_PATH。

​	使用该软件包时，需要将shell线程的堆栈大小尽可能调大，建议改为**8192**或以上为最稳妥。

​	随后编译下载之后，可以在shell终端看到一个名为"L"的命令，该命令即为Lua的命令行工具。

​	L命令有两种使用方式：

1.  直接在输入单行的Lua命令:

   ```shell
   L math.pi
   ```

   上述命令使用了Lua内置数学库来打印pi的值，Lua组件工作正常的话，会在命令行看到如下回复：

   ![image-20211204154728272](png/image-20211204154728272.png)

2. 输入以.lua结尾的lua脚本文件名称

   ```shell
   L test.lua
   ```

   上述命令会运行文件系统中的test.lua脚本

LuaOne软件包会在初始化时自动读取名为init.lua的脚本文件进行初始化操作，所有需要提前定义的变量或lua函数建议放到此处（注意文件内字符数量不要超出设定的buffer缓冲区最大值）。随后，解释器会查找main.lua并进行循环执行（注意，main.lua的循环执行是靠C语言循环执行main.lua内文本实现的，所以不要在mina,lua脚本内再次书写死循环结构，否则将导致操作系统无法正常工作甚至卡死。）如果没有找到main.lua脚本，则初始化步骤完成。此时，仍可以通过串口shell的方式运行init.lua内定义的函数和变量。

## 3. 向解释器注册C函数

​	软件包提供了两个函数接口用于用户注册自己的函数，注册函数的代码位于软件包lua_port/lua_pin.c.

​	代码如下图所示：

```c
#include "luarun.h"

static int pin_write(lua_State *L) //Lua规定的调用函数的定义形式
{
	int iPin = lua_tonumber(L,1); //将Lua参数转化为C语言可接受的类型	
    int iState = lua_tonumber(L,2);
    os_pin_write((os_base_t)iPin, (os_base_t)iState);
	return 0;
}

static int pin_mode(lua_State *L)
{
	int iPin = lua_tonumber(L,1);	
    int iMode = lua_tonumber(L,2);
    os_pin_mode((os_base_t)iPin, (os_base_t)iMode);
	return 0;
}

static int Pin_init(void)
{
    lua_rd_t iNo; //定义一个reg句柄
    iNo = LUA_REG("Pin"); //此接口用于定义一个类，此行表示定义一个名为“Pin”的类
    LUA_FUN(iNo, "write", pin_write); //此接口用于将函数注册到刚才定义的"Pin"类中，函数在lua中的名称为write
    LUA_FUN(iNo, "mode", pin_mode);
    return iNo;
} 
OS_ENV_INIT(Pin_init, OS_INIT_SUBLEVEL_LOW);
```

​	首先需要包含**luarun.h**以调用两组接口，随后，按照Lua的要求对函数进行定义（详细的被lua调用的C函数的格式可以参考Lua官方文档）

​	**lua_tonumber**是Lua官方规定的接口，用于将Lua脚本的参数转化为C语言的数据类型。

| 函数名  | 作用                  | 入参                                                 | 返回值                     |
| ------- | --------------------- | ---------------------------------------------------- | -------------------------- |
| LUA_REG | 定义一个reg类         | reg的名称(const char *)                              | reg句柄(lua_rd_t)          |
| LUA_FUN | 向指定reg类中注册函数 | reg句柄(lua_rd_t)，函数名称(const char *)，C中的函数 | 函数在reg数组的索引值(int) |

​	上述代码生效后，在命令行下输入：`L Pin.write(89,1)`就相当与调用了OneOS中的`os_pin_write(89,1)`

## 4. 教程推荐

​	关于lua编程语言可以参考如下文档

[Lua 5.3 参考手册中文版](http://cloudwu.github.io/lua53doc/contents.html).  

## 5. 感谢

1. 该库基于 https://github.com/lua/lua 移植. 
2. 感谢Lua团队. 本移植是修改了部分原作者的代码针对OneOS实现的版本, 该仓库保留原作者的许可声明! 具体原作者许可请查看 https://www.lua.org/license.html, 移植代码部分保留 https://github.com/liu2guang/Lua2RTT/blob/master/LICENSE 许可. 
3. 本次移植作者：绯红杀杀，仅用于参加2021年中国移动举办的OneOS代码贡献大赛。