oakctl 工具
oakctl 工具
oakctl 是一个命令行工具,允许您与 OAK4 相机进行交互。它可用于创建、部署和管理运行 oak-agent 服务并在本地网络上的应用程序和设备。
oakctl。安装
Linux/MacOS
在 64 位系统上,运行:
Command Line
1bash -c "$(curl -fsSL https://oakctl-releases.luxonis.com/oakctl-installer.sh)"更新
oakctl 工具:Command Line
1oakctl self-updateWindows 更新问题
如果您在 Windows 上更新 oakctl 版本时遇到问题,请从 此处 下载安装程序。
用法
连接到设备
Command Line
1oakctl connectCommand Line
1oakctl connect 10.0.1.24--with-password 标志存储设备的密码。这样可以避免每次会话过期时都输入密码。查找设备
oakctl 允许您与安装了 oak-agent 的设备进行交互。您可以使用以下命令列出所有可用设备(在您的网络中找到):Command Line
1oakctl list
2+---+---------------+---------------+------------+----------------+---------------+-------+
3| # | 序列号 | 设备 | 连接 | 操作系统 | Agent 版本 | 设置 |
4+=========================================================================================+
5| 1 | 1623452492 | Luxonis, Inc. | 10.0.1.24 | OS RVC4 1.18.0 | 0.13.7 | OK |
6| | | OAK4-D R7 | | | | |
7+---+---------------+---------------+------------+----------------+---------------+-------+应用开发
Command Line
1oakctl app run /app/path/to/sourceoakctl app run 使用提供的应用程序目录中的 oakapp.toml。 使用 --oakapp-file 选择备用配置文件(例如 oakapp.dev.toml 或 oakapp.prod.toml),前提是该文件位于同一应用程序目录树内。可选标志:
| 标志 | 描述 |
|---|---|
-b, --detach | 在分离模式下运行应用程序。您可以使用 oakctl app stop <APP_ID> 停止它。 |
-d, --device [<DEVICE>] | 使用 IP、IP:PORT、索引或 oakctl list 中的序列号指定设备。 |
-i, --invalidate | 使缓存无效并强制重新构建。 |
-e, --env <KEY=VALUE> | 将运行时环境变量导出到应用程序(可以提供多次)。 |
--env-file <FILE> | 从 .env 文件导出运行时环境变量。 |
--oakapp-file [<PATH>] | 使用应用程序目录树内的备用 oakapp.toml 文件(例如开发/生产变体)。 |
--preserve-line-endings | 上传文件到设备之前禁用自动 CRLF 到 LF 转换。 |
示例应用
oakapp.toml:Command Line
1git clone https://github.com/luxonis/oak-examples.git
2cd oak-examples
3# 运行应用程序
4oakctl app run ./neural-networks/pose-estimation/human-pose # 或其他示例环境变量
-e, --env 标志或 --env-file 标志将环境变量传递给应用程序。这些变量将在应用程序的运行时环境中可用,可用于配置应用程序而无需更改代码。Command Line
1oakctl app run ./app/path --env KEY1=VALUE1 --env KEY2=VALUE2build_env 字段在 oakapp.toml 文件中设置这些变量,或在构建时使用 --build-arg 标志传递它们:Command Line
1oakctl app build ./app/path --build-arg KEY1=VALUE1 --build-arg KEY2=VALUE| 变量 | 描述 |
|---|---|
OAKAGENT_APP_ID | 唯一的应用 ID。 |
OAKAGENT_CONTAINER_ID | 容器 ID(如果应用已更新,可能与应用 ID 不同)。 |
OAKAGENT_APP_IDENTIFIER | 来自 oakapp.toml 的应用标识符。 |
OAKAGENT_APP_VERSION | 来自 oakapp.toml 的应用版本。 |
DEPTHAI_ZOO_MODELS_PATH | DepthAI Zoo 模型目录的路径;根据 oakapp.toml 中的 depthai_models 字段设置;建议不要手动修改。 |
DEPTHAI_ZOO_CACHE_PATH | DepthAI Zoo 缓存目录的路径;用于缓存下载的模型;建议不要手动修改。 |
DEPTHAI_ZOO_INTERNET_CHECK | 启用模型下载的互联网连接检查;根据 oakapp.toml 中的 depthai_models 字段设置;建议不要手动修改。 |
DEPTHAI_DEVICE_NAME_LIST | 在所有 RVC4 设备上设置为 127.0.0.1,以确保独立应用仅使用其正在运行的设备,即使网络上有多个设备。 |
OAKAPP_STATIC_FRONTEND_PATH | 应用静态前端文件的路径。 |
OAKAPP_STATIC_FRONTEND_PORT | 用于提供静态前端文件的端口。它从 9000-9128 的范围内设置,以避免与代理或其他应用使用的端口冲突。 |
OAKAGENT_STORAGE_APP | 应用特定的持久存储路径。 |
OAKAGENT_STORAGE_SHARED | 跨具有相同标识符的应用共享的存储路径。 |
OAKAGENT_STORAGE_GLOBAL | 设备上的全局存储路径。 |
持久化存储
持久化存储路径用于存储应在应用重启和更新后保留的数据。这些路径会被挂载到应用的容器中。您可以使用
oakapp.toml 配置 (storage_dir_name) 选择容器中存储的目标目录名称。OAKAGENT_STORAGE_APP是每个应用独有的存储路径,不与其他应用共享。它适用于存储不应被其他应用访问的应用特定数据。OAKAGENT_STORAGE_SHARED是所有具有相同标识符的应用之间共享的存储路径。它适用于存储应被不同应用实例访问的数据。OAKAGENT_STORAGE_GLOBAL是一个全局存储路径,不与任何特定应用绑定。它适用于存储无论安装或运行哪些应用都应可访问的数据。
应用管理
-d, --device <DEVICE>,用于指定运行命令的设备(IP 地址或 oakctl list 中的索引)。列出已安装的应用
com.luxonis.default)。Command Line
1$ oakctl app list
2+---+--------+---------------------------+---------+-------------------+
3| E | App Id | Identifier | Status | Frontend URL |
4+====================================================================================================+
5| * | f8da5 | com.luxonis.default:1.3.8 | running | 10.0.1.24:9000 |
6+---+--------+---------------------------+---------+-------------------+E) 中的星号表示该应用已启用。任何应用都可能处于以下状态之一:installing(安装中)、building(构建中)、ready(就绪)、starting(启动中)、running(运行中)、 stopping(停止中)、stopped(已停止)、deleting(删除中)、deleted(已删除)、unknown(未知)。Ready 表示应用已安装并准备运行,但自代理启动以来尚未启动;而 stopped 表示应用已安装但未运行,已被用户停止。注意
为提高可读性,应用 ID 在列表中被截断。如果存在多个具有相同前缀的应用,截断长度会增加,直到所有应用 ID 都唯一。您也可以使用
--long 标志在列表中显示完整的应用 ID。所有应用控制命令都接受完整和截断的应用 ID,只要它们是唯一的。应用控制流程
start、stop 和 delete。首先,我们来启动应用:Command Line
1$ oakctl app start 612a745c-8d68-4264-a3d6-d06d14275ef5
2Starting app 612a745c-8d68-4264-a3d6-d06d14275ef5 ...
3 App has been started!Command Line
1$ oakctl app start 612a745cCommand Line
1$ oakctl app logs <app-id>
2Reading logs ...
3 Press Ctrl+C to stop reading logs.
4 App output:
5 [2025-02-12T14:37:54Z] Hello cli 1 / Wed Feb 12 14:37:54 UTC 2025-n 标志指定要读取的先前行数:Command Line
1oakctl app logs <app-id> -n 10Command Line
1oakctl app logs <app-id> --no-followCommand Line
1$ oakctl app stop 612a745c-8d68-4264-a3d6-d06d14275ef5
2Stopping app 612a745c-8d68-4264-a3d6-d06d14275ef5 ...
3 App has been stopped!Command Line
1$ oakctl app delete 612a745c-8d68-4264-a3d6-d06d14275ef5
2Deleting app 612a745c-8d68-4264-a3d6-d06d14275ef5 ...
3 App has been deleted!Command Line
1oakctl app enable <app-id>disable 命令禁用该应用:Command Line
1oakctl app disable <app-id>exec 命令:Command Line
1oakctl app exec <app-id> -i /bin/bash