LuatOS扩展库API——【exremotecam】网络摄像头控制

一、概述

exremotecam 扩展库是 LuatOS 提供的一个网络摄像头控制工具，它通过 WiFi 网络或以太网连接到指定的网络摄像头，实现对摄像头的 OSD (屏幕显示) 文字设置和拍照功能。

你可以把它想象成一个简易的摄像头远程控制工具：

网络连接：设备需要保持与摄像头在同一局域网内，通过 WiFi 或以太网连接到与摄像头相同的网络
OSD 控制：设置摄像头屏幕上显示的文字内容、位置和对齐方式
远程拍照：控制摄像头进行拍照，并将照片保存到设备的 SD 卡中

该库适用于需要远程控制网络摄像头进行 OSD 设置和拍照的应用场景，如视频监控系统、智能安防设备等。

注意事项：

使用 SD 卡功能保存照片之前，如果使用核心板，需要参考 AirMICROSD_1010 配件板使用说明将 AirMICROSD_1010 配件板与核心板用杜邦线链接，确保 SD 卡能够正常挂载和使用
使用前需要先加载具体品牌的摄像头功能模块
所有参数都通过统一的配置表传递，支持更灵活的参数配置

二、核心示例

1、核心示例是指：使用本库文件提供的核心 API，开发的基础业务逻辑的演示代码；

2、核心示例的作用是：帮助开发者快速理解如何使用本库，所以核心示例的逻辑都比较简单；

3、更加完整和详细的 demo，请参考 LuatOS 仓库中Air8101产品目录下的 module/Air8101/demo/control_network_camera

网络摄像头 OSD 控制示例

lua 复制代码

--[[
本核心示例的业务逻辑为：
1、连接到网络
2、挂载SD卡
3、设置摄像头OSD文字显示
4、控制摄像头拍照并保存到SD卡
]]

PROJECT = "CONTROL_NETWORK_CAMERA"
VERSION = "001.000.000"

-- 在日志中打印项目名和项目版本号
log.info("main", PROJECT, VERSION)

-- 连接WiFi网络
log.info("执行STA连接操作")
wlan.connect("@PHICOMM_75", "li19760705")

-- 等待WiFi连接成功
while not socket.adapter(socket.LWIP_STA) do
    sys.waitUntil("IP_READY", 1000)
end

-- 挂载SD卡
-- 演示使用 Air8101 核心板+AirMICROSD_1010 配件板挂载sd卡
-- gpio13为8101 SD卡的供电控制引脚，在挂载前需要设置为高电平，不能省略
gpio.setup(13, 1)
-- 在Air8101核心板上TF卡的的pin_cs为gpio3，spi_id为1.请根据实际硬件修改
spi_id, pin_cs = 1, 3
spi.setup(spi_id, nil, 0, 0, 400 * 1000)
--初始化后拉高pin_cs,准备开始挂载TF卡
gpio.setup(pin_cs, 1)
-- ########## 开始进行tf卡挂载 ##########
local mount_ok, mount_err = fatfs.mount(fatfs.SPI, "/sd", spi_id, pin_cs, 24 * 1000 * 1000)
log.info("SDCARD", "挂载SD卡结果:", mount_ok)

-- 导入摄像头模块（注意加载顺序：先加载具体品牌模块，再加载主模块）
local dhcam = require "dhcam"
local exremotecam = require "exremotecam"

-- 设置摄像头OSD文字显示（使用table参数格式）
local osd_result = exremotecam.osd({
    brand = "dhcam",
    host = "192.168.1.108",
    channel = 0,
    text = "行1|行2|行3|行4|行5|行6",
    x = 0,
    y = 2000
})
log.info("OSD设置结果:", osd_result)

-- 等待OSD设置完成
sys.wait(1000)

-- 控制摄像头拍照并保存到SD卡（使用table参数格式）
local photo_result = exremotecam.get_photo({
    brand = "dhcam",
    host = "192.168.1.108",
    channel = 1
})
log.info("拍照结果:", photo_result)

-- 用户代码已结束--------------------------------------------
-- 结尾总是这一句
sys.run()
-- sys.run()之后不要加任何语句!!!!!因为添加的任何语句都不会被执行

三、常量详解

exremotecam 扩展库没有常量

四、函数详解

4.1 exremotecam.osd(camera_param)

功能

设置摄像头的 OSD (屏幕显示) 文字内容和位置

注意事项

当前仅支持大华 ("dhcam") 品牌的摄像头；
OSD 文本内容需要用竖线 (|) 分隔，每行表示一行文字；
大华摄像头最多支持显示 13 行文字；
X 和 Y 坐标用于控制 OSD 显示的位置；
确保设备已连接到与摄像头相同的网络；
使用前需要先加载具体品牌的摄像头功能模块（如 dhcam），再加载 exremotecam 主模块。

参数

camera_param

lua 复制代码

> 参数含义：摄像头参数配置表；参数为table类型时，table内容格式说明如下：  
> {  
> 参数含义：摄像头品牌；  
> 数据类型：string；  
> 取值范围："dhcam"（当前仅支持大华品牌）；  
> 是否必选：必选传入此参数；  
> 注意事项：必须填写正确的品牌名称；  
> 参数示例："dhcam"，表示使用大华品牌摄像头；  
> 参数名称：camera\_param.brand
> 
> 参数含义：摄像头/NVR的IP地址；  
> 数据类型：string；  
> 取值范围：有效的IP地址；  
> 是否必选：必选传入此参数；  
> 注意事项：必须是有效的摄像头IP地址；  
> 参数示例："192.168.1.108"，摄像头IP地址；  
> 参数名称：camera\_param.host
> 
> 参数含义：摄像头通道号；  
> 数据类型：number；  
> 取值范围：根据摄像头型号而定；  
> 是否必选：可选传入此参数；  
> 注意事项：单摄像头通常使用通道0，默认为0；  
> 参数示例：0，使用通道0；  
> 参数名称：camera\_param.channel
> 
> 参数含义：OSD文本内容；  
> 数据类型：string；  
> 取值范围：用竖线分隔的多行文字；  
> 是否必选：必选传入此参数；  
> 注意事项：大华摄像头最多支持13行文字；  
> 参数示例："温度: 25℃|湿度: 60%|时间: 2025-01-01"，显示三行文字；  
> 参数名称：camera\_param.text
> 
> 参数含义：OSD显示位置的X坐标；  
> 数据类型：number；  
> 取值范围：根据摄像头分辨率而定；  
> 是否必选：可选传入此参数；  
> 注意事项：X坐标决定了OSD显示的水平位置，默认为0；  
> 参数示例：0，X坐标为0；  
> 参数名称：camera\_param.x
> 
> 参数含义：OSD显示位置的Y坐标；  
> 数据类型：number；  
> 取值范围：根据摄像头分辨率而定；  
> 是否必选：可选传入此参数；  
> 注意事项：Y坐标决定了OSD显示的垂直位置，默认为0；  
> 参数示例：2000，Y坐标为2000；  
> 参数名称：camera\_param.y  
> }  
> 
> 数据类型：table；  
> 取值范围：参考参数含义内各字段说明  
> 是否必选：必须传入此参数；  
> 注意事项：所有参数都通过table传递；  
> 参数示例：  
> {  
> brand = "dhcam",  
> host = "192.168.1.108",  
> channel = 0,  
> text = "行1|行2|行3",  
> x = 0,  
> y = 2000  
> }

返回值

boolean

lua 复制代码

返回值含义：OSD设置结果；
数据类型：boolean；
取值范围：false - 设置失败，true - 设置成功；
注意事项：可以通过返回值判断操作是否成功；
返回值示例：true；

示例

-- 大华摄像头OSD测试

lua 复制代码

local result = exremotecam.osd({
    brand = "dhcam",
    host = "192.168.0.163",
    channel = 0,
    text = "行1|行2|行3",
    x = 0,
    y = 2000
})
log.info("OSD设置结果:", result)

-- 多通道NVR示例

lua 复制代码

local result = exremotecam.osd({
    brand = "dhcam",
    host = "192.168.0.200",
    channel = 1,
    text = "温度: 25℃|湿度: 60%",
    x = 100,
    y = 50
})
log.info("OSD设置结果:", result)

4.2 exremotecam.get_photo(camera_param)

功能

控制网络摄像头进行拍照，并将照片保存到设备的 SD 卡中

注意事项

当前仅支持大华 ("dhcam") 品牌的摄像头；
确保设备已连接到与摄像头相同的网络；
如果要保存照片，使用前需要先挂载 SD 卡；
照片将保存为 /sd/1.jpeg；
如果未挂载 SD 卡，将无法保存照片；
使用前需要先加载具体品牌的摄像头功能模块（如 dhcam），再加载 exremotecam 主模块。

参数

camera_param

返回值

number

lua 复制代码

返回值含义：拍照操作结果；
数据类型：number；
取值范围：0 - 拍照失败，1 - 拍照成功且照片保存到指定路径，2 - 拍照成功但照片保存失败；
注意事项：可以通过返回值判断操作结果和照片保存状态；
返回值示例：1；

示例

-- 获取大华摄像头通道0的快照图片（指定自定义保存路径）

lua 复制代码

local result = exremotecam.get_photo({
    brand = "dhcam",
    host = "192.168.1.108",
    channel = 0,
    save_path = "/sd/camera1.jpeg"
})
log.info("拍照结果:", result)

-- 获取大华NVR通道1的快照图片（使用默认保存路径）

lua 复制代码

local result = exremotecam.get_photo({
    brand = "dhcam",
    host = "192.168.0.200",
    channel = 1
})
log.info("拍照结果:", result)

五、常见问题与解决方案

5.1 无法连接到网络摄像头

问题描述：调用函数后，日志显示无法连接到摄像头

解决方案：

检查设备是否已成功连接到网络；
确认摄像头的 IP 地址是否正确；
确保设备与摄像头在同一网络中；
检查摄像头是否正常工作，可通过电脑访问摄像头 IP 进行测试；
确认是否正确加载了摄像头品牌模块（如 dhcam）和 exremotecam 主模块。

5.2 OSD 设置不生效

问题描述 ：调用 osd 函数后，摄像头屏幕上没有显示设置的文字

解决方案：

确认摄像头品牌是否为 "dhcam"（当前仅支持大华品牌）；
检查 OSD 文本内容是否使用竖线正确分隔；
确认 X 和 Y 坐标设置是否在摄像头分辨率范围内；
查看日志输出，检查是否有错误信息；
确认参数是否正确使用 table 格式传递。

5.3 模块加载失败

问题描述：运行时提示模块加载错误或函数未定义

解决方案：

确认模块加载顺序：先加载具体品牌模块（如 dhcam），再加载 exremotecam 主模块；
检查模块文件是否存在且路径正确；
确认使用的函数名称是否正确（osd 和 get_photo，不是 OSDsetup 和 getphoto）。

4.4 参数传递错误

问题描述：函数调用时报参数错误或类型错误

解决方案：

确认所有参数都通过 table 格式传递，而不是独立参数；
检查参数名称是否正确（如 brand、host、channel 等）；
确认必选参数是否都已提供；
查看函数返回值，根据返回值判断操作结果。

六、模组支持说明

支持 LuatOS 开发的所有产品都支持 exremotecam 库