Skip to content

BMP AgriStack Standard Operating Procedure

LoRaWAN Network Server System (AgriStack)

Document Control - Version: 1.0 - Date: November 10, 2025 - Prepared by: Christopher Brant, PhD - Approved by: Doug Crawford

1. Purpose and Scope

1.1 Purpose

This Standard Operating Procedure (SOP) defines the operational guidelines, maintenance procedures, and troubleshooting protocols for the LoRaWAN network server system utilizing AgriStack (based on the ChirpStack framework). The AgriStack server contains: - LoRaWAN network server for maintenance, organization, and traffic flow control of our full LoRaWAN network infrastructure. - Iris middleware server for forwarding Dragino SDI-12-CS (or LS) SDI-12 Data Logger data logger packets sent from cellular networking devices via MQTT. - Iris middleware server for forwarding Dragino SDI-12-CS (or LS) SDI-12 Data Logger data logger packets sent from LoRaWAN networking devices through our ChirpStack-based infrastructure. - Phoenix middleware server for forwarding all data from any data collection devices sent from LoRaWAN networking devices through our ChirpStack-based infrastructure. - Python-based Flask API for front-end based interaction with our ChirpStack network server for Phoenix devices. - Python-based Flask API for R&D/testing and validation for any type of device that can send via webhook/HTTP requests.

1.2 Scope

This document covers: - System architecture and components - Daily operational procedures - User and device management - Monitoring and maintenance - Troubleshooting procedures - Security protocols - Backup and recovery procedures

2. System Overview

2.1 AgriStack Architecture

The LoRaWAN network server consists of the following core components based on the ChirpStack framework:

  • ChirpStack Gateway Bridge: Converts packet forwarder protocols to ChirpStack format
  • ChirpStack Network Server: Handles LoRaWAN network layer
  • ChirpStack Application Server: Provides device management and application integration
  • MQTT Broker (Mosquitto): Message broker for device data
  • PostgreSQL Database: Stores configuration and operational data
  • Redis: Handles caching and temporary data storage

2.2 System Requirements

  • Operating System: Linux (Ubuntu 20.04 LTS or later recommended)
  • Minimum RAM: 4GB (8GB recommended for production)
  • Minimum Storage: 50GB SSD
  • Network: Static IP address with appropriate firewall rules

3. Access and Authentication

3.1 User Access Levels

  • Super Admin: Full system access, user management, global configuration
  • Organization Admin: Organization-level device and user management
  • Device Manager: Device provisioning and monitoring
  • Read-Only User: View-only access to devices and data

3.2 Login Procedure

  1. Navigate to AgriStack web interface: https://agristack.bmplogic.net
  2. Enter username and password
  3. Enable two-factor authentication if configured
  4. Verify successful login and appropriate dashboard access

4. Daily Operations

4.1 System Health Check (Daily)

Procedure: 1. Log into AgriStack Application Server 2. Navigate to Dashboard 3. Verify the following metrics: - Active gateways count matches expected deployment - Device activity showing recent uplinks - Online devices count - Devices with issues (alerts/errors) - Total active devices - Total inactive devices - No critical alerts in system logs

  1. Check gateway connectivity:
  2. Navigate to Gateways section
  3. Review "Last Seen" timestamps
  4. Investigate any gateways offline > 15 minutes

Expected Results: - All services operational - Gateway availability > 95% - Message success rate > 95%

Action on Failure: - Document issues in system log - Escalate according to Section 7 (Troubleshooting)

5. Device Management

5.1 Device Registration

Pre-requisites: - Device EUI (DevEUI) - Application/Join EUI (AppEUI/JoinEUI) - Application Key (AppKey) or ABP session keys - Device profile matching device specifications

Procedure:

  1. Create Device Profile (if not existing):
  2. Navigate to Device Profiles
  3. Click Create
  4. Configure:
    • Name and description
    • LoRaWAN MAC version
    • Regional parameters band
    • Class (A, B, or C)
    • Expected uplink interval

  5. Save device profile

  6. Register Device:

  7. Navigate to Applications > Select Application
  8. Click Devices > Create
  9. Enter device information:
    • Device name
    • Description
    • Device EUI
    • Device profile

  10. Click Create Device

  11. Configure Activation:

  12. For OTAA (Recommended):
    • Enter Application Key (AppKey)
    • Note: JoinEUI configured at application level

  13. For ABP:

    • Enter Device Address
    • Network Session Key (NwkSKey)
    • Application Session Key (AppSKey)
    • Frame counters (typically 0 for new devices)

  14. Verify Registration:

  15. Check device appears in application device list
  16. Status shows "Never seen" until first uplink

Documentation: Record in device inventory spreadsheet: - Device name and DevEUI - Installation location - Date registered - Associated application - Contact person/department

5.2 Device Decommissioning

Procedure: 1. Navigate to Applications > Select Application > Devices 2. Select device to decommission 3. Review device activity history and export if needed 4. Click Delete Device 5. Confirm deletion 6. Update device inventory documentation 7. If physical device removal, coordinate with field team

6. Gateway Management

6.1 Gateway Registration

Pre-requisites: - Gateway EUI - Network connectivity to ChirpStack server - Packet forwarder configured on gateway

Procedure: 1. Navigate to Gateways > Create 2. Enter gateway information: - Gateway name - Gateway EUI - Network server (select appropriate server) - Service profile - GPS coordinates (if available) 3. Configure gateway settings: - Expected gateway altitude - Gateway discovery enabled (recommended) 4. Click Create Gateway

6.2 Gateway Configuration

On Gateway Device: - See either DLOS8N Gateway Configuration or WisGate Edge Pro Gateway Configuration for the proper configuration for the chosen gateway hardware.

6.3 Gateway Monitoring

Daily Checks: - Verify "Last Seen" within last 5 minutes - Check RX/TX packet counts incrementing - Review gateway location on map view

Weekly Checks: - Analyze gateway statistics - Review signal quality metrics - Check for firmware updates

Action Items: - Offline > 4 hours: Create incident ticket - Poor signal quality: Schedule site survey - Firmware available: See CTO if necessary to schedule maintenance window

7. Troubleshooting Procedures

7.1 Device Not Joining Network (OTAA)

Symptoms: - Device shows "Never seen" status - Join requests not appearing in gateway/device logs

Troubleshooting Steps: 1. Verify device is powered and transmitting 2. Check device is within gateway coverage 3. Review gateway live logs for join requests: - Navigate to Gateways > Select Gateway > LoRaWAN Frames 4. Verify device credentials: - DevEUI matches device hardware - AppKey is correct - JoinEUI matches application configuration 5. Check device profile regional settings match gateway 6. Review network server logs for join-accept messages: 

sudo journalctl -u chirpstack-network-server | grep -i join
7. Verify network server can reach devices (check firewall rules)

Resolution: - Correct any credential mismatches - Adjust device or gateway placement if signal issue - Re-provision device if persistent failure

7.2 Gateway Offline

Symptoms: - Gateway "Last Seen" > 15 minutes - No recent packet activity

Troubleshooting Steps: 1. Check network connectivity to gateway - Ping gateway IP address - Verify network route to AgriStack server 2. Verify AgriStack services running: 

sudo systemctl status chirpstack-gateway-bridge
sudo systemctl status chirpstack-network-server
3. Check gateway-bridge logs: 
sudo journalctl -u chirpstack-gateway-bridge -n 100
4. Review firewall rules (UDP ports 1700 must be open) 5. If gateway accessible, verify packet forwarder running: 
systemctl status packet-forwarder
6. Check gateway power and physical connections

Resolution: - Restart affected services - Reconfigure network if routing issues - Dispatch field technician if hardware failure suspected

7.3 High Packet Loss

Symptoms: - Device uplink success rate < 90% - Frequent retransmissions

Troubleshooting Steps: 1. Check gateway signal quality metrics 2. Review device RSSI and SNR values (Navigate to device > LoRaWAN Frames) 3. Identify if issue is isolated to: - Single device: Check device location/antenna - Single gateway: Check gateway performance - Multiple devices: Check network congestion 4. Review spreading factor and data rate configuration 5. Check for interference sources on frequency band 6. Analyze duty cycle compliance

Resolution: - Relocate device or gateway if signal poor - Add additional gateway if coverage gap - Adjust ADR settings if appropriate - Investigate and remove interference sources

8. Security Procedures

8.1 Access Control

User Management: - Review user accounts every 6 months - Disable accounts for departed personnel immediately - Implement principle of least privilege - Require strong authentication for all accounts

8.2 Network Security

Firewall Configuration: Required open ports: - 8080/TCP: Web interface (HTTPS recommended) - 1700/UDP: Gateway packet forwarder - 1883/TCP: MQTT broker (internal only) - 5432/TCP: PostgreSQL (localhost only) - 6379/TCP: Redis (localhost only)

9. Integration Management

9.1 Application Integrations

AgriStack supports multiple integration methods: - HTTP Integration: REST API endpoints - MQTT Integration: Message broker publishing - InfluxDB: Time-series data storage - PostgreSQL: Direct database integration

HTTP Integration Setup: 1. Navigate to Applications > Select Application > Integrations 2. Click Add > Select HTTP 3. Configure: - Endpoint URL - Headers (authentication tokens) - Event types to forward 4. Test integration with sample payload 5. Monitor integration logs for errors

10. Performance Monitoring

10.1 Key Performance Indicators (KPIs)

Tech Stack KPIs - Device Issues Rate: Target < 5%

Network KPIs: - Gateway availability: Target > 99% - Device join success rate: Target > 95% - Uplink success rate: Target > 95% - Average message latency: Target < 2 seconds - Packet loss rate: Target < 5%

10.2 Monitoring Tools

Built-in Monitoring: - AgriStack Dashboard metrics - Gateway statistics - Device frame logs - System event logs

End of Document

This SOP should be reviewed and updated at least annually or whenever significant system changes occur.