openwrt LuCI

文章列表

openwrt LuCI

LuCI 介绍

LuCI 成立于 2008 年 3 月，名称为“FFLuCI”，为 OpenWrt 固件从 Whiterussian 到 Kamikaze 实现快速配置接口。用于嵌入式设备的免费、干净、可扩展且易于维护的 Web 用户界面。 LuCI 可以实现路由的网页配置界面，是 LUA 与 UCI的合体。

UCI 是 OpenWrt 中为实现所有系统配置的一个统一接口，英文名 Unified Configuration Interface ，即统一配置接口。

LUA(入门) 是一个小巧的脚本语言，轻量级的官方版本只包括一个精简的核心和最基本的库。这使得 LUA 体积小、启动速度快，从而适合嵌入在别的程序里。我们主要工作是基于 LuCI 框架编写LUA 脚本、在 html 页面中嵌入 LUA 脚本。

LuCI使用 Lua 编程语言并将界面拆分为模型和视图等逻辑部分，使用面向对象的库和模板。这确保了更高的性能、更小的安装尺寸、更快的运行时间以及更重要的是：更好的可维护性。与此同时，
LuCI 从一个 MVC-Webframework 演变为一个包含了很多库、应用程序和用户界面的集合，而重点仍然放在 Web 用户界面上，这也成为了 OpenWrt Kamikaze 的官方部分。LuCI 是一个开放源码的独立项目。参考LuCI wiki。

添加 LuCI

LuCI --->Collections ---><*> luci<*> luci-sslModules  ---> <*> luci-compat //可以帮助解决一些兼容性问题，推荐一同安装

luci 包含依赖 +uhttpd +luci-mod-admin-full +luci-theme-bootstrap +luci-app-firewall +luci-app-opkg +luci-proto-ppp +libiwinfo-lua +IPV6:luci-proto-ipv6 +rpcd-mod-rrdns太多，可以精简一些：

LuCI --->Collections --->< > luci #不需要选Modules  ---> <*> luci-compat #可以帮助解决一些兼容性问题，推荐一同安装<*> luci-mod-admin-full #LUCI_DEPENDS:=+luci-base +luci-mod-status +luci-mod-system +luci-mod-networkTranslations---><*> luci-i18n-chinese<*> luci-i18n-englishThemes  ---><*> luci-theme-bootstrap#luci Makefile LUCI_DEPENDS 包含 @BROKEN 表示此模块是不稳定的，有性能问题或存在缺陷。且不会在menuconfig中加载。

新建 LuCI 应用模块

大多数 LuCI 代码位于目标系统的目录中/usr/lib/lua/luci，而 Web 资源（JavaScript、CSS 等）位于/www目标系统的目录中。
我们要做的主要工作就是基于 LuCI 框架编写LUA 脚本、在 html 页面中嵌入 LUA 脚本。

参考 Adding new elements to LuCI 在 feeds/luci/applications/ 创建luci-app-myapplication应用。

应用目录

# tree luci-app-myapplication
├── Makefile
└── luasrc├── controller│   └── myapp│       └── new_tab.lua├── model│   └── cbi│       └── myapp-module   │          └── cbi_tab.lua└── view└── myapp-module      └── view_tab.htm
# luci-app-myapplication 对应的 uci 配置文件
package/base-files/files/etc/config/cbi_file

Makefile

在 luci-app-myapplication 目录中添加 Makefile 文件：

include $(TOPDIR)/rules.mkLUCI_TITLE:=LuCI Support for Test
LUCI_DEPENDS:=include ../../luci.mk# call BuildPackage - OpenWrt buildroot signature

cbi_file

config 'info' 'A' option 'name' 'OpenWRT'

MVC文件

LuCI采用了MVC (模型/视图/控制)三层架构，在系统的 /usr/lib/lua/luci/下有三个目录 model、 view、 controller。参考

model 指的是 cbi 模型，经过高度封装直接映射 /etc/config/下的UCI文件生成页面表单，简单易用但无法自定义。

view 是可以嵌入 lua 的 HTML 文件。可以自由定义页面样式，需要前端知识。

controller 生成一些url路径，并指定这些url对应 model中的cbi生成的页面 或者 view中的html页面 或者是 call执行函数(定义在文件下方即可) 等。

可参考源码 feeds/luci/applications/luci-app-xx/luasrc/

controller控制器

在Luci web中注册名为"New tab"的菜单项，包含三个子项"CBI Tab",“View Tab"和"Call Tab”,分别展示CBI配置页面,视图页面和调用action页面。

注册名为 "New tab"的菜单项，设置访问权限级别为60，不依赖其他菜单项。

注册名为 "CBI Tab"的子菜单项，访问排序为1。点击时系统将调用 cbi 返回 cbi_tab.lua 模型生成的CBI配置表单页面。

注册名为 "View Tab"的子菜单项，访问排序为2。点击时系统将调用 template 返回渲染后的 view_tab.htm 视图页面。注册 set_hostname 函数，可嵌入View页面调用。

注册名为 "Call Tab"的子菜单项，访问排序为3。点击时系统将调用 action_reboot 函数，无页面。

luci-app-myapplication/luasrc/controller/myapp/new_tab.lua 文件：

module("luci.controller.myapp.new_tab", package.seeall) --路径对应
function index() --菜单项的入口函数。当用户访问这个菜单项时，系统将执行这个函数。entry({"admin", "new_tab"}, firstchild(), "New tab", 60).dependent=falseentry({"admin", "new_tab", "tab_from_cbi"}, cbi("cbi_tab"), "CBI Tab", 1)entry({"admin", "new_tab", "tab_from_view"}, template("view_tab"), "View Tab", 2)entry({"admin", "new_tab", "call_act_reboot"}, call("action_reboot"), "Call Tab", 3).dependent=falseentry({"admin", "new_tab", "call_act_sethost"}, call("set_hostname"))
endfunction action_reboot()luci.http.prepare_content("text/plain")luci.http.write("Rebooting now...")luci.sys.reboot()
endfunction set_hostname()local hostname = luci.http.formvalue("hostname")local executeString = "uci set system.@system[0].hostname="..hostnameluci.sys.exec(executeString)
end

luci.dispatcher 中的 entry 函数可以在dispatching tree中完成模块节点的注册。
entry(path, target, title=nil, order=nil)

path: 虚拟路径。例如：{"admin", "new_tab", "tab_from_cbi"} 对应 /cgi-bin/luci/admin/new_tab/tab_from_cbi 。

target: 分派时要调用的目标函数。3个最重要的函数(call, template, cbi)。

call 执行指定方法(Action)。如上述代码: call("action_reboot") 以及定义 action_reboot 函数。

template用来调用已有的htm模版，模版目录在lua\\luci\\view目录下。

cbi语句使用cbi模块，这是使用非常频繁也非常方便的模块，在cbi模块中定义各种控件，Luci系统会自动执行大部分处理工作。其链接目录在lua\\luci\\model\\cbi下。

alias 指向另一菜单入口。

arcombine 有参与无参组合调度。

luci.dispatcher 其他函数

title: 定义在菜单中对用户可见的标题(可选)。

order: 菜单栏中的排序数值(可选)，由上至下，由左至右，依次递增。

可以通过操作入口函数返回的节点表来分配更多属性。一些示例属性：

i18n: 定义了当页面被请求时应该自动加载哪个翻译文件

dependent: 保护插件在父节点缺失时脱离上下文调用

leaf: 在这个节点上停止解析请求，在调度树中不再继续

sysauth: 要求用户使用给定的系统用户帐户进行身份验证

view 视图文件

LuCI是一个简单的基于正则表达式的模板处理器，可以将HTML文件解析为Lua函数，并允许存储预编译的模板文件。最简单的形式只是一个普通的HTML文件，将原样显示给用户。

在LuCI中每个模板都是一个具有自己作用域的对象。因此，它可以被实例化，每个实例都可以具有不同的作用域。LuCI支持几个特殊的标记。这些标记被包含在<% %>标签中。

通过在开头的 <% 后面添加 - 可以去除标记之前的所有空格。在闭合 %> 前面加上 - 将相应地去除标记后面的所有空格。

为了提升用户体验，form页应该使用ajax来传输数据。

luci-app-myapplication/luasrc/view/myapp-module/view_tab.htm 文件

<%+header%>
<p>Setting the IP address</p>
<form method="get" action="<%=luci.dispatcher.build_url("admin", "new_tab", "call_act_sethost")%>">
<input type="text" name="hostname">
<button id="submit">提交</button>
<%+footer%>

语法说明

1、包含Lua代码: <% code %>

2、输出变量和函数值： <% write(value) %> 或 <%=value%>

3、包含模板: <% include(templatesName) %> 或 <%+templatesName%>

4、翻译： <%=translate(“Text to translate”) %> 或 <%:Text to translate%>

5、注释： <%# comment %>

内置常量

REQUEST_URI: 当前 URL (没有服务器部分)

controller: Luci 主调度器的路径

resource: 资源目录路径

media：活动主题目录的路径

其他语法跟html和JavaScript一样。

model 模型文件

编写 LuCI CBI 模型

luci-app-myapplication/luasrc/model/cbi/myapp-module/cbi_tab.lua 文件:

m = Map("cbi_file", translate("First Tab Form"), translate("Please fill out the form below")) -- 映射/etc/config/中的uci文件
d = m:section(TypedSection, "info", "Part A of the form")
a = d:option(Value, "name", "Name"); a.optional=false; a.rmempty = false;
return m

Map() 函数创建了一个名为 m 的表单映射对象，它将映射到 /etc/config/ 目录下的 cbi_file 文件。

m:section() 函数创建一个名为 d 的区域对象（TypedSection），将包含表单的第一个选项卡 Part A of the form。

d:option() 函数在该区域对象上创建一个名为 a 的选项（Value），它将对应表单中的一个文本输入框，用于输入名称。a.optional=false 表示选项必填，a.rmempty=false 表示必须输入值才能提交表单。

return 语句返回整个表单映射对象 m，以便在 OpenWrt LuCI 界面上显示该表单。

添加应用

./scripts/feeds update luci
./scripts/feeds install -a -p luci
make menuconfig

代码修改

通常可以直接在系统上编辑所有文件。但要注意，LuCI 框架在/tmp目录中缓存其 Lua 库的预编译变体，建议使用uci set luci.ccache.enable=0; uci commit luci以禁用代码缓存以用于开发目的。

新建LuCI主题

themes/luci-theme-mytheme 示例。

主题目录

# tree luci-theme-mytheme
├── Makefile
├── htdocs
│   └── luci-static
│       └── mytheme
├── luasrc
│   └── view
│       └── themes
│           └── mytheme
│               ├── footer.htm
│               └── header.htm
└── root└── etc└── uci-defaults└── 30_luci-theme-mytheme

Makefile

在 luci-theme-mytheme 目录中添加 Makefile 文件：

include $(TOPDIR)/rules.mkLUCI_TITLE:=Title of mythemeinclude ../../luci.mk
# call BuildPackage - OpenWrt buildroot signature

设计主题

在 luasrc/view/themes/mytheme 中的 header.htm将包含在每个呈现页面的开头，footer.htm将包含在末尾。

所以header.htm可能会包含DOCTYPE描述，页眉，菜单和页面布局，footer.htm将关闭所有剩余的打开标签，并可能添加一个页脚栏。

要确保header.htm从以下几行开始：

<%
require("luci.http").prepare_content("text/html")
-%>

这将确保内容将以正确的内容类型发送到客户端。也可以根据自己的需要调整text/html。

将任何stylesheets、Javascript、images等放入htdocs/luci-static/mytheme。需要在页眉和页脚模板中将此目录称为：<%=media%>。
例如：对于 htdocs/luci-static/mytheme/cascade.css 需编写：

<link rel="stylesheet" type="text/css" href="<%=media%>/cascade.css" />

使主题可选

为了使主题在 OpenWrt 设置页面上可选择，root/etc/uci-defaults/luci-theme-mytheme包含以下内容的文件：

#!/bin/shif [ "$PKG_UPGRADE" != 1 ]; thenuci get luci.themes.Mytheme >/dev/null 2>&1 || \\uci batch <<-EOFset luci.themes.Mytheme=/luci-static/mythemeset luci.main.mediaurlbase=/luci-static/mythemecommit luciEOF
fiexit 0

其他模块

参考教程:LuCI Modules ，LuCI模块分为几个类别目录，即：

applications（其他模块或应用程序的单个应用程序或插件）
i18n（翻译文件）
libs（独立库）
modules（应用程序的集合）
themes（前端主题）

模块目录

Makefile : 如果模块只包含 Lua 源代码或资源，那么下面的 Makefile 就足够了。

include $(TOPDIR)/rules.mkLUCI_TITLE:=Title of my example applications
LUCI_DEPENDS:=+some-package +libsome-library +luci-app-anotherthinginclude ../../luci.mk# call BuildPackage - OpenWrt buildroot signature

如果模块中有 C(++) 代码，应该包含一个 src/ 子目录，其中包含另一个支持clean ,compile 和 install target 的 Makefile。install target 应该相对于预定义的$(DESTDIR)变量部署其文件，例如

mkdir -p $(DESTDIR)/usr/bin; cp myexecutable $(DESTDIR)/usr/bin/myexecutable

src: 该src目录是为 C 源代码保留的。
luasrc: luasrc包含所有 Lua 源代码文件。将根据 Make 目标自动剥离或编译，并安装在 LuCI 安装目录中。
lua: lua相当于luasrc但是包含lua的文件会被安装到lua文件根目录下。
htdocs: htdocs下的所有文件将被复制到目标网络服务器的文档根目录。
root：root下所有目录和文件将原样复制到安装目标。
dist: dist保留给构建器来创建一个工作安装树，它将代表目标机器上的文件系统。不要将任何文件放在那里，因为它们会被删除。
ipkg: ipkg包含 IPKG 包控制文件，如preinst, posinst, prerm, postrm. conffiles. 有关详细信息，请参阅 IPKG 文档。

feed 整合

如果想将模块添加到 LuCI OpenWRT feed 中，必须将这几个部分添加到contrib/package/luci/Makefile.

对于 Web UI 应用程序：

# A package description:
define Package/luci-app-YOURMODULE$(call Package/luci/webtemplate)DEPENDS+=+some-package +some-other-packageTITLE:=SHORT DESCRIPTION OF YOURMODULE
endef# A package installation target:
define Package/luci-app-YOURMODULE/install$(call Package/luci/install/template,$(1),applications/YOURMODULE)
endef# A module build instruction:
ifneq ($(CONFIG_PACKAGE_luci-app-YOURMODULE),)PKG_SELECTED_MODULES+=applications/YOURMODULE
endif# A build package call:
$(eval $(call BuildPackage,luci-app-YOURMODULE))

其他参考链接

LuCI 0.10.x 的重要变化
HowTo: 使用 JSON-RPC API
参考:LuCI API文档(Lua)
参考:LuCI JavaScript API 文档(客户端)
教程:i18n
参考:LMO文件格式

openwrt LuCI

openwrt LuCI

LuCI 介绍

添加 LuCI

新建 LuCI 应用模块

应用目录

MVC文件

controller控制器

view 视图文件

model 模型文件

添加应用

代码修改

新建LuCI主题

主题目录

设计主题

使主题可选

其他模块

模块目录

feed 整合

其他参考链接

相关问题

公告

标签