Brokkr

数据采集/记录/上行链路客户端，作为Mjolnir系统的一部分，用于远程管理和自主及集中控制科学物联网传感器。最初是为了接收本地HAMMA2闪电传感器和Sunsaver MPPT-15L充电控制器发送的科学数据和状态信息，并将其存储在本地，然后将其传输回中央服务器（通常是运行Sindri软件包的服务器，但并非必须），但现在正在发展为可扩展和可配置，适用于各种应用，从低成本、低功耗的数百个环境监测传感器阵列，到安装在飞机和无人机上的复杂仪器。此外，它还可以维护一个反向SSH隧道到可访问的服务器，以便远程访问，并通过该连接接收并执行作为TCP数据包转发的电源、处理系统和传感器控制命令。

Mjolnir项目的目标是让没有编码背景的PI或学生能够轻松开始收集和分析来自低成本传感器的数据，并允许那些有基本编程经验的人轻松开发、测试和共享自己的插件，以与新的传感器、输出等功能一起工作，只需进行少量或没有额外的工作，但具有重大的长期效益。长期愿景是创建一个开源预设、插件、示例等多种低成本的科学物联网传感器的生态系统。

主要功能

• 支持SPI、I2C、GPIO、模拟、SMBus、UART、Modbus、TCP、UDP等多种作为输入，以及内置的打印/美观打印、文件和系统记录、CSV和TCP数据包作为输出
• 易于使用、功能强大的插件框架，具有简单的API和最小的模板化步骤，用于输入、处理和输出步骤；可以是放置在特定目录中的简单Python文件，也可以是正确的Python软件包
• 提供警报/触发动作、Slack通知、REST/web API等多种插件的插件
• 内置支持多种传感器，包括ECH2O EC-5、EC-10、EC-20、DS18S20、DS1822、DS18B20、DS28EA00、DS1825、MAX31850K、HIH6130、Si7021、SHT31D、MPL3115A2、MLX90614、HTU21D、DHT11、DHT22、BMP280、BME280、MPPT-15L、HAMMA2、ADS1015、ADS1115以及通用开关、计数器、GPIO和模拟风速计方向和速度，以及时间、运行时间、ping等
• 内置支持新传感器、设备和新协议的声明性预设系统；预设可以通过在主配置文件中添加一行来启用，并通过配置选项进行广泛的定制
• 强大的错误处理、状态记录、自动安装、服务配置和多进程管理基础设施
• 分层配置系统，允许多级设置和覆盖
• 系统无关且完全多系统兼容；所有元数据、配置、插件和预设都存储在VCS可跟踪的自包含包中，便于管理

许可

版权所有（c）2019-2022 C.A.M. Gerlach，UAH HAMMA小组和Mjolnir项目贡献者

本软件根据MIT (Expat) 许可证分发；有关详细信息，请参阅LICENSE.txt。

安装和设置

Brokkr是在Python 3.6-3.10下构建和测试的，具有相对最小的轻量级、纯Python核心依赖。它在Linux上表现最佳，但在Windows（以及应在macOS上同样运行）上经过测试，完全功能（除服务功能外），使用Anaconda发行版。

标准安装

在Linux（或其他平台，对于有经验的用户）上，Brokkr可以像任何其他Python包一样安装，通过pip将其安装到venv虚拟环境中。

例如，在当前工作目录中的ENV_DIR内创建venv，并根据需要安装支持特定传感器类型所需的额外包（例如modbus、serial、adafruit等，或all以安装所有这些包）

python3 -m venv ENV_DIR
source ENV_DIR/bin/activate
pip install brokkr[EXTRA1,EXTRA2...]

在Windows和Mac上，建议使用Anaconda/Miniconda，用conda环境代替venv。虽然这些平台受到开发支持，但某些特定于在生产环境中运行Brokkr的功能可能不可用。

有关安装开发版本的说明，请参阅贡献指南。

接下来，您需要再进行几个步骤来设置环境：克隆您想与 Brokkr 一起使用的系统配置包（将示例 mjolnir-config-template 路径替换为您自己的），注册它们，并设置您的配置和单元信息。SYSTEM_SHORTNAME 是您希望在系统文件中注册的系统名称，而 UNIT_NUMBER 是您想指定您正在安装的设备的整数编号（任意，但应该是唯一的）。

git clone https://github.com/project-mjolnir/mjolnir-config-template.git
brokkr configure-system SYSTEM_SHORTNAME /path/to/system/mjolnir-config-template
brokkr configure-init
brokkr configure-unit UNIT_NUMBER

最后，您可以根据系统的需要运行安装后的设置步骤。首先，您需要安装任何系统特定的依赖项，

brokkr install-dependencies

然后，为了在启动时运行 Brokkr，只需安装 Systemd 服务单元，运行

sudo /PATH/TO/ENV_DIR/bin/python -m brokkr install-service``
brokkr install-dependencies

如果您需要，可以设置特定的账户、安装路径和启动参数；有关更多用法和选项信息，请参阅 brokkr install-service --help。

对于安装所有设置后的任务（包括配置文件、脚本、系统特定依赖项、防火墙访问以及 Linux 上的串行端口访问、Brokkr systemd 服务和 SSH/AutoSSH 服务及配置），您可以运行

sudo /PATH/TO/ENV_DIR/bin/python -m brokkr install-all
brokkr install-dependencies

最后，您可以使用 brokkr --version、brokkr status 和 brokkr --help 中详细说明的其他命令来检查 Brokkr 是否已正确安装和设置。简单地重新启动以自动完成设置并启动 brokkr 服务，或在所有平台上，您可以在命令行上立即手动执行它，使用 brokkr start。

自动清理安装（开发中）

对于在运行现代基于 Linux 的操作系统的典型物联网设备（例如 Raspberry Pi 之类的单板计算机）上的设置，Brokkr 具有全面的设置程序，可以引导工厂新系统的所有关键方面，以便在野外部署。只需声明您要复制的配置文件，您要安装/启用/禁用/删除的软件包和服务，您要打开/关闭的防火墙端口，以及每个安装阶段的其他自定义操作（移动文件、sed 脚本、运行的命令等），作为系统配置包的一部分，在您的命令下，brokkr 将完成剩余的工作。

一个典型的半自动化安装流程可能如下所示

1. 将 OS 图像闪存到 SD 卡中
2. 执行基本的 raspi-config、Fedora 等设置；如果需要，更改用户名
3. 创建并激活 venv，从离线 sdist 使用 pip install brokkr --no-dependencies 并复制系统配置目录和任何密钥文件
4. 运行 brokkr configure-system <systemname> <systempath> 来设置系统配置目录路径
5. 运行 brokkr install --phase 1 以执行启用互联网所需的必要步骤
6. 更新所有软件包到最新版本（apt update && apt full-upgrade && apt autoremove）并重新安装带有所有软件包的 brokkr（pip uninstall brokkr && pip install brokkr）
7. 运行 brokkr install --phase 2 以安装剩余的项目
8. 运行 brokkr setup-device 以触发特定于设备的设置操作
9. 为 Sindri 创建 venv 并 pip install sindri 它（可选）
10. 一旦到达现场，执行单元配置（见下文）

将提供示例 bash 脚本，它会自动运行此工作流程的第 3-9 步，可以根据特定系统的需求进行定制。

将 Brokkr 闪存到准备好的卡中

如果已通过“自动清理安装”部分中提到的步骤（不包括 brokkr setup-device 步骤）准备好了一张卡，将其闪存到另一台设备上并准备部署非常简单。

1. 在闪存 Pi 并激活适当的 venv 后，运行 brokkr setup-device 以重新生成特定于设备的 harness 项目（密码、散列、SSH 密钥等）。您需要在交互式提示符下输入 Pi 的当前密码和所需的密码。
2. 最后，在现场，一旦设置了最终单元配置（或将来更改后），按照以下方式进行现场设置

现场设置

在现场，您需要采取一些额外操作来将特定设备与特定地点配对，并测试连接。

1. 运行 brokkr configure-unit <单元编号> --network-interface <网络接口> 来设置基本单元配置
2. 运行 brokkr setup-unit 执行每个单元的最终现场设置，注册并测试与传感器的链接，并验证与上游服务器的连接
3. 关闭设备电源，将其连接到所有所需的硬件并重新启动

用法

概述

请参阅 brokkr --help 和 brokkr <SUBCOMMAND> --help 以获取 Brokkr 的 CLI、调用、选项和子命令的详细文档。以下是一个简明扼要的概述。

要快速检查 Brokkr、其版本以及当前系统（如果已配置），请使用 brokkr --version。运行 brokkr status 命令以获取监控数据的快照，并使用 brokkr monitor 命令以实时（默认情况下每秒1次）获取所有主要监控变量的美观显示。 brokkr start 是 Brokkr 核心功能的主要入口点，加载和执行配置的数据采集、处理和输出管道，在正常使用中通过 Brokkr 服务运行。

brokkr install-* 命令执行安装功能，而 brokkr configure-* 功能有助于设置新的或更新的 brokkr 安装。在 Linux 上，可以通过标准 systemd 命令与 brokkr-SYSTEMNAME systemd 服务交互，例如 sudo systemd {start, stop, enable, disable} brokkr-SYSTEMNAME，systemd status brokkr-SYSTEMNAME，journalctl -u brokkr-SYSTEMNAME 等，对于 autossh-brokkr，它控制远程 SSH 连接。

交互式使用（前台）

首先，激活适当的 Python 虚拟环境（例如 source ENV_DIR/bin/activate）。

然后，您有几个选择

• 主要前台启动命令，用于测试：brokkr start
• 一次性状态输出：brokkr status
• 轻量级实时监控（打印到屏幕，也可以写入文件）：brokkr monitor

作为服务运行 Brokkr（后台）

• 自动生成、安装和启用服务
  • sudo /home/pi/path/to/ENV_DIR/bin/python -m brokkr install-service
• 启动/停止
  • sudo systemctl start brokkr-SYSTEMNAME
  • sudo systemctl stop brokkr-SYSTEMNAME
• 启用/禁用启动时运行
  • sudo systemctl enable brokkr-SYSTEMNAME
  • sudo systemctl disable brokkr-SYSTEMNAME
• 基本状态检查和最新日志输出
  • systemctl status brokkr-SYSTEMNAME
• 完整日志输出（也记录到文本文件 ~/brokkr/hamma/brokkr_hamma_NNN.log）
  • journalctl -xe -u brokkr-SYSTEMNAME

配置

Brokkr 和 Mjolnir 系统的主要设计目标是广泛、灵活且直观的重新配置，以适应不同的传感器网络和不断变化的需求。例如，对于 UAH HAMMA2 系统，除了每个单元的几个特定的高层次元素外，所有系统配置通常都通过为该系统开发的标准的 Mjolnir 配置方案中的 Mjolnir-HAMMA 系统配置包 来处理，这些高层次元素都有以下交互式配置命令。

但是，如果需要超出此处指定的这些高层次选项的本地自定义，而不是直接修改版本控制跟踪的系统配置包，那么为此构建的配置系统是完全分层的，所有设置都可以通过 ~/.config/brokkr/SYSTEM_NAME 中的相应本地配置完全覆盖。Brokkr 完全支持同时配置、记录、操作和输出任意数量的 Mjolnir 系统，所有这些都位于同一台 Pi 上。

配置文件位于XDG标准~/.config/brokkr目录下，采用类似ini的TOML格式；可以通过运行brokkr configure-init（如果文件已存在则不会覆盖）来生成，并使用brokkr configure-reset将其重置为默认值。

高级本地设置配置

注册、更新和删除系统

注册Mjolnir系统

brokkr configure-system <SYSTEM-NAME> </PATH/TO/SYSTEM/CONFIG/DIR>

（例如：brokkr configure-system hamma /home/pi/dev/mjolnir-hamma）

您也可以使用此命令通过适当的参数删除、更新、验证和设置默认系统；请参阅brokkr configure-system --help

生成本地配置文件

如果尚未存在，则生成空本地每个系统（即覆盖）配置文件

brokkr configure-init

设置每个单元的配置

brokkr configure-unit <UNIT_NUMBER> --network-interface <INTERFACE>

（例如：brokkr configure-unit 1 --network-interface wlan0）

重置配置

重置单元和本地覆盖配置（可选地减去系统注册表）

brokkr configure-reset