LoRaWAN服务器API开发指南：REST、WebSocket、MQTT接口的完整使用教程

【免费下载链接】lorawan-server Compact server for private LoRaWAN networks 项目地址: https://gitcode.com/gh_mirrors/lo/lorawan-server

LoRaWAN服务器是构建私有LoRaWAN网络的核心组件，提供了REST、WebSocket和MQTT三种接口用于设备数据的双向通信。本教程将详细介绍如何使用这些接口与LoRaWAN服务器进行高效交互，帮助开发者快速实现设备数据的采集与控制。

LoRaWAN服务器接口架构概述

LoRaWAN服务器采用模块化设计，通过不同的连接器组件实现与外部系统的通信。系统架构图展示了REST、WebSocket和MQTT接口在整体系统中的位置和交互方式：

从架构图中可以看出，三种接口通过不同的连接器模块与服务器核心组件交互：

• REST API：通过HTTP请求处理器与服务器交互
• WebSocket：通过专门的WebSocket连接器实现实时通信
• MQTT：通过MQTT连接器与外部MQTT broker通信

所有接口最终都与服务器的核心处理模块和数据库交互，实现设备数据的存储、处理和转发。

REST API接口使用详解

REST API是LoRaWAN服务器最基础也是应用最广泛的接口，支持设备管理、数据查询和配置更新等功能。

基本信息与认证

REST API默认通过服务器的8080端口提供服务，所有API端点都以/api/开头。访问API需要使用HTTP摘要认证，默认用户名和密码均为"admin"。

核心API端点

LoRaWAN服务器提供了丰富的REST API端点，以下是一些常用的端点：

资源路径	支持方法	说明
/api/nodes	GET, POST	管理活跃的网络节点
/api/nodes/{devaddr}	GET, PUT, DELETE	操作指定DevAddr的节点
/api/rxframes	GET	查询最近接收的帧数据
/api/queued	GET	获取待发送的下行帧队列
/api/connectors	GET	管理后端连接器

数据查询示例

查询指定设备的接收帧数据：

curl --digest -u admin:admin "http://localhost:8080/api/rxframes?_filters={\"devaddr\":\"22222222\"}"

使用排序和分页参数获取最近的10条接收帧：

curl --digest -u admin:admin "http://localhost:8080/api/rxframes?_sortField=datetime&_sortDir=DESC&_page=1&_perPage=10"

设备管理示例

添加新的ABP设备：

curl --digest -u admin:admin -H "Content-Type: application/json" -X POST http://localhost:8080/api/nodes -d '[
  {
    "devaddr": "00000001",
    "profile": "Semtech Mote",
    "nwkskey": "00000000000000000000000000000000",
    "appskey": "00000000000000000000000000000000",
    "fcntdown": 0
  }
]'

发送下行数据

通过REST API发送下行数据到指定设备：

curl --digest -u admin:admin -H "Content-Type: application/json" -X POST http://localhost:8080/in/00000001 -d '{"data":"ABCDEFG"}'

WebSocket接口实时通信

WebSocket接口提供了全双工的实时通信能力，适合需要实时监控设备数据的场景。

连接器配置

要使用WebSocket接口，首先需要在服务器中创建WebSocket连接器：

1. 设置URI为ws:
2. 配置Publish Uplinks为URL模式，如/ws/uplink/{devaddr}
3. 配置Publish Events为另一个URL模式，如/ws/events/{devaddr}
4. 可选择设置认证信息

连接WebSocket

客户端可以通过以下URL连接到WebSocket接口：

ws://server:8080/ws/uplink/<DevAddr>

例如，连接到DevAddr为11223344的设备数据：

ws://127.0.0.1:8080/ws/uplink/11223344

演示页面

服务器提供了一个WebSocket测试页面，位于http://127.0.0.1:8080/admin/ws.html。通过该页面可以方便地测试WebSocket连接和数据收发。

保持连接

默认情况下，如果客户端1小时内没有数据发送，WebSocket连接将被关闭。可以通过以下方式保持连接：

1. 调整服务器配置中的websocket_timeout参数
2. 客户端定期发送ping帧
3. 设置{websocket_timeout, infinity}禁用超时（不推荐生产环境使用）

MQTT接口使用指南

MQTT接口适用于与外部MQTT broker集成，实现设备数据的发布和订阅。

连接器配置

创建MQTT连接器需要以下关键配置：

1. URI：MQTT broker地址，如mqtt://host:port或mqtts://host:port（SSL加密）
2. Publish Uplinks：上行消息主题模式，如out/{devaddr}
3. Subscribe：下行消息订阅主题，如in/#
4. Received Topic：下行消息解析模板，如in/{devaddr}
5. QoS级别：设置发布和订阅的QoS级别

发布上行数据

服务器会自动将设备上行数据发布到配置的MQTT主题。例如，当配置out/{devaddr}作为发布主题时，DevAddr为00112233的设备数据将发布到out/00112233主题。

可以使用MQTT客户端订阅这些主题来接收设备数据：

mosquitto_sub -h 127.0.0.1 -p 1883 -t 'out/#' -u 'user' -P 'pass'

发送下行数据

通过MQTT发送下行数据到设备：

mosquitto_pub -h 127.0.0.1 -p 1883 -t 'in/00112233' -m '{"data":"00"}' -u 'user' -P 'pass'

MQTT主题模式

MQTT连接器支持在主题中使用占位符，如{devaddr}和{appargs}，实现动态主题生成。例如：

• 设置Client ID为{devaddr}将为每个设备创建独立的MQTT连接
• 使用out/{deveui}作为发布主题可以基于设备EUI进行数据路由

接口选择与最佳实践

接口特性对比

接口类型	优势	适用场景
REST API	简单易用，广泛支持，适合单次请求	设备管理、配置更新、历史数据查询
WebSocket	实时性好，双向通信，低延迟	实时监控、实时数据展示
MQTT	轻量级，低带宽占用，支持发布/订阅	设备数据长期采集、与IoT平台集成

安全最佳实践

1. 认证与授权：始终使用强密码，并根据需求创建不同权限的用户
2. 数据加密：生产环境中应使用HTTPS、WSS和MQTTS加密传输
3. 输入验证：对所有API输入进行验证，防止注入攻击
4. 定期更新：保持服务器软件最新，及时修复安全漏洞

性能优化建议

1. 批量操作：使用批量API减少请求次数
2. 合理分页：查询大量数据时使用分页参数
3. 连接复用：WebSocket和MQTT连接应尽量复用，避免频繁创建和关闭
4. 数据过滤：使用过滤参数只获取需要的数据

常见问题与故障排除

连接问题排查

1. 检查服务器是否正常运行：curl http://localhost:8080/api/servers
2. 验证REST API可访问性：wget http://your_server:8080/api/servers
3. 检查防火墙设置，确保8080端口开放

权限问题

确保用户具有适当的权限范围，特别是发送下行数据需要device:send权限。可以在服务器配置中检查和修改用户权限。

数据格式问题

1. REST API和WebSocket默认使用JSON格式
2. 二进制数据应使用十六进制字符串表示
3. MQTT支持JSON和原始数据格式，需在连接器中配置

总结

LoRaWAN服务器提供的REST、WebSocket和MQTT接口为开发者提供了灵活多样的设备交互方式。通过本指南，您应该已经掌握了这些接口的基本使用方法和最佳实践。选择合适的接口类型，结合实际应用场景，可以构建高效、可靠的LoRaWAN应用系统。

如需了解更多详细信息，请参考项目中的官方文档：

• 连接器配置
• 服务器管理
• 集成指南

【免费下载链接】lorawan-server Compact server for private LoRaWAN networks 项目地址: https://gitcode.com/gh_mirrors/lo/lorawan-server