diff --git a/CODE REVIEW/ARDUINO_COMPILATION_GUIDE.md b/CODE REVIEW/ARDUINO_COMPILATION_GUIDE.md index 69f2c54..3d2e129 100644 --- a/CODE REVIEW/ARDUINO_COMPILATION_GUIDE.md +++ b/CODE REVIEW/ARDUINO_COMPILATION_GUIDE.md @@ -2,7 +2,7 @@ This guide helps ensure Arduino sketches compile successfully in the CI workflow and locally. -## Quick Verification +## Quick Verification - 092025 (MKR NB 1500) To verify your changes compile correctly before committing: @@ -25,6 +25,33 @@ arduino-cli compile --fqbn arduino:samd:mkrnb1500 \ TankAlarm-092025-Server-Hologram/TankAlarm-092025-Server-Hologram.ino ``` +## Quick Verification - 112025 (Arduino Opta) + +To verify the 112025 sketches compile: + +```bash +# Install Arduino CLI (if not already installed) +curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | sh +export PATH="$PWD/bin:$PATH" + +# Setup cores and libraries for Arduino Opta +arduino-cli core update-index +arduino-cli core install arduino:mbed_opta +arduino-cli lib install "ArduinoJson@7.2.0" +arduino-cli lib install "Blues Wireless Notecard" +arduino-cli lib install "Ethernet" + +# Compile Client sketch +arduino-cli compile --fqbn arduino:mbed_opta:opta \ + TankAlarm-112025-Client-BluesOpta/TankAlarm-112025-Client-BluesOpta.ino + +# Compile Server sketch +arduino-cli compile --fqbn arduino:mbed_opta:opta \ + TankAlarm-112025-Server-BluesOpta/TankAlarm-112025-Server-BluesOpta.ino +``` + +**Note:** LittleFS and Wire libraries are built into the Arduino Mbed OS core and don't need separate installation. + ## Common Compilation Issues ### 1. Type Name Errors @@ -103,18 +130,32 @@ Keep resource usage reasonable: ## Configuration Files -### Client Configuration +### 092025 Configuration (MKR NB 1500) +**Client Configuration:** - **Template:** `TankAlarm-092025-Client-Hologram/config_template.h` - **Active:** Include `config_template.h` for compilation (users create their own `config.h`) - **Tracked:** Only `config_template.h` is in git (config.h is .gitignored) -### Server Configuration - +**Server Configuration:** - **Hardware Config:** `TankAlarm-092025-Server-Hologram/server_config.h` (compile-time hardware constants) - **SD Card Config:** `TankAlarm-092025-Server-Hologram/server_config.txt` (runtime user configuration) - **Tracked:** Hardware config.h is in git; SD card .txt template is tracked +### 112025 Configuration (Arduino Opta) + +**Client Configuration:** +- **Runtime Config:** `/client_config.json` stored in LittleFS (internal flash) +- **Default config created automatically** on first boot +- **Product UID:** Update `PRODUCT_UID` define in `.ino` file to match Blues Notehub project +- **No SD card required** + +**Server Configuration:** +- **Runtime Config:** `/server_config.json` stored in LittleFS (internal flash) +- **Default config created automatically** on first boot +- **Product UID:** Update `SERVER_PRODUCT_UID` define in `.ino` file to match Blues Notehub project +- **No SD card required** + ## Troubleshooting ### Local Compilation Works but CI Fails @@ -130,6 +171,54 @@ Keep resource usage reasonable: 2. Missing hardware-specific libraries 3. Different board variant (check FQBN) +## Common Compilation Issues - 112025 (Arduino Opta) + +### 1. ArduinoJson Version Mismatch + +**Problem:** `no matching function for call to 'JsonDocument::JsonDocument(int)'` + +**Solution:** Ensure you have ArduinoJson version 7.x or later: +- ArduinoJson 7.x uses `JsonDocument` instead of `DynamicJsonDocument` +- Install via Library Manager: Search "ArduinoJson" and install version 7.2.0 or later +- Version 6.x will not work with the 112025 code + +### 2. Notecard Library Missing + +**Problem:** `Notecard.h: No such file or directory` + +**Solution:** Install Blues Wireless Notecard library: +- Open Library Manager +- Search: "Notecard" +- Install: "Blues Wireless Notecard by Blues Inc." + +### 3. LittleFS Not Found + +**Problem:** `LittleFS.h: No such file or directory` + +**Solution:** LittleFS is built into Arduino Mbed OS core: +- Go to **Tools → Board → Boards Manager** +- Search: "Arduino Mbed OS Opta Boards" +- Install the package +- LittleFS will be automatically available + +### 4. Wrong Board Selected + +**Problem:** `#error "This sketch is designed for Arduino Opta"` + +**Solution:** Ensure correct board is selected: +- Go to **Tools → Board → Arduino Mbed OS Opta Boards** +- Select **Arduino Opta** +- FQBN should be: `arduino:mbed_opta:opta` + +### 5. Ethernet Library Issues + +**Problem:** Ethernet-related compilation errors (server only) + +**Solution:** +- Ethernet library should be built-in +- If missing, install via Library Manager: "Ethernet by Arduino" +- Ensure you're compiling the server, not the client (client doesn't use Ethernet) + ## Best Practices 1. **Always test locally** before pushing @@ -139,9 +228,20 @@ Keep resource usage reasonable: 5. **Check resource usage** after adding features 6. **Verify closing braces** match opening ones 7. **Keep sketches modular** with clear function separation +8. **For 112025:** Ensure ArduinoJson 7.x is installed (not 6.x) +9. **For 112025:** Verify Mbed OS Opta core is installed for LittleFS support ## Additional Resources +### 092025 (MKR NB 1500) - [Arduino CLI Documentation](https://arduino.github.io/arduino-cli/) - [MKRNB Library Reference](https://www.arduino.cc/reference/en/libraries/mkrnb/) - [Arduino MKR NB 1500 Documentation](https://docs.arduino.cc/hardware/mkr-nb-1500) + +### 112025 (Arduino Opta) +- [Arduino Opta Documentation](https://docs.arduino.cc/hardware/opta) +- [Blues Wireless Notecard Library](https://dev.blues.io/tools-and-sdks/firmware-libraries/arduino-library/) +- [ArduinoJson v7 Documentation](https://arduinojson.org/v7/) +- [Arduino Mbed OS Documentation](https://docs.arduino.cc/learn/programming/mbed-os-basics) +- [Client Installation Guide](../TankAlarm-112025-Client-BluesOpta/INSTALLATION.md) +- [Server Installation Guide](../TankAlarm-112025-Server-BluesOpta/INSTALLATION.md) diff --git a/QUICK_REFERENCE_FLEET_SETUP.md b/QUICK_REFERENCE_FLEET_SETUP.md index 919f18d..ea921f0 100644 --- a/QUICK_REFERENCE_FLEET_SETUP.md +++ b/QUICK_REFERENCE_FLEET_SETUP.md @@ -1,5 +1,31 @@ # Quick Reference: Fleet-Based vs Route-Based Setup +## Arduino IDE Setup (112025) + +### Required Software +- **Arduino IDE** 2.0+ (recommended) or 1.8.x +- **Board Support:** Arduino Mbed OS Opta Boards (via Boards Manager) + +### Required Libraries (Install via Library Manager) +1. **ArduinoJson** (version 7.x or later) - JSON parsing +2. **Blues Wireless Notecard** (latest) - Notecard communication +3. **Ethernet** (built-in) - Web server (server only) +4. **LittleFS** (built-in with Mbed core) - File system +5. **Wire** (built-in) - I2C communication + +### Installation Steps +1. Install Arduino IDE from [arduino.cc/software](https://www.arduino.cc/en/software) +2. Open **Tools → Boards Manager** → Search "Arduino Mbed OS Opta Boards" → Install +3. Open **Tools → Manage Libraries** → Install libraries listed above +4. Open sketch (.ino file) for client or server +5. Select **Tools → Board → Arduino Opta** +6. Update `PRODUCT_UID` (client) or `SERVER_PRODUCT_UID` (server) to match your Blues Notehub project +7. Compile and upload + +**📚 Detailed Instructions:** +- [Client Installation Guide](TankAlarm-112025-Client-BluesOpta/INSTALLATION.md) +- [Server Installation Guide](TankAlarm-112025-Server-BluesOpta/INSTALLATION.md) + ## At a Glance | Aspect | Route-Based (OLD) | Fleet-Based (NEW) ✅ | diff --git a/README.md b/README.md index fc1c4c2..29619ff 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,43 @@ Arduino LTE cellular system that monitors tank levels and sends SMS alerts when Arduino will check sensor data on a scheduled basis. If sensor data is over a set threshold, the arduino will send an SMS text message to defined phone numbers. It will also send a daily reading of the sensor data at a set time of day. -## Version 092025 (Current - Recommended) +## Version 112025 (Blues Wireless + Arduino Opta) + +The 112025 version uses Arduino Opta with Blues Wireless Notecard for cellular connectivity. Features include: +- **Internal flash storage** (LittleFS) - No SD card required +- **Fleet-based communication** - Simplified device-to-device data exchange via Blues Notehub +- **Web-based configuration** - Update clients remotely from server dashboard +- **Intranet dashboard** - Real-time monitoring via Ethernet web interface + +### Quick Links - 112025 Client (Tank Monitor) +- **[Installation Guide](TankAlarm-112025-Client-BluesOpta/INSTALLATION.md)** - Complete Arduino IDE setup with library installation +- **[Fleet Implementation Summary](TankAlarm-112025-Client-BluesOpta/FLEET_IMPLEMENTATION_SUMMARY.md)** - Architecture overview +- **[Migration Guide](TankAlarm-112025-Client-BluesOpta/MIGRATION_GUIDE.md)** - Upgrading from route-based setup + +### Quick Links - 112025 Server (Data Aggregation) +- **[Installation Guide](TankAlarm-112025-Server-BluesOpta/INSTALLATION.md)** - Complete Arduino IDE setup with library installation +- **[Fleet Setup Guide](TankAlarm-112025-Server-BluesOpta/FLEET_SETUP.md)** - Blues Notehub fleet configuration + +### Configuration Approach (112025) + +The 112025 version uses a **simplified configuration system**: + +1. **LittleFS Internal Storage** - Configuration persisted to device flash + - No SD card required + - Survives power cycles + - Automatic default config on first boot + +2. **Remote Configuration** - Update clients via server web interface + - Push config changes from server to any client + - Changes routed through Blues Notehub + - No physical access needed for updates + +3. **Fleet-Based Communication** - Simplified device-to-device routing + - Just assign devices to fleets in Blues Notehub + - No manual route configuration needed + - Easier scaling for multiple devices + +## Version 092025 (Current - Recommended for MKR NB 1500) The 092025 version is the latest implementation using Arduino MKR NB 1500 with Hologram.io cellular connectivity. diff --git a/TankAlarm-112025-Client-BluesOpta/INSTALLATION.md b/TankAlarm-112025-Client-BluesOpta/INSTALLATION.md new file mode 100644 index 0000000..ff8e865 --- /dev/null +++ b/TankAlarm-112025-Client-BluesOpta/INSTALLATION.md @@ -0,0 +1,363 @@ +# TankAlarm-112025-Client-BluesOpta Installation Guide + +This guide walks you through setting up the Arduino IDE and installing the TankAlarm 112025 Client sketch on an Arduino Opta with Blues Wireless Notecard. + +## Hardware Requirements + +- **Arduino Opta Lite** - [Purchase Link](https://store-usa.arduino.cc/products/opta-lite) +- **Blues Wireless for Opta** - [Purchase Link](https://shop.blues.com/collections/accessories/products/wireless-for-opta) +- **Arduino Pro Opta Ext A0602** (for analog sensor inputs) - [Purchase Link](https://store-usa.arduino.cc/products/opta-ext-a0602) +- **USB-C cable** for programming +- **Sensors** - Compatible analog sensors for tank level monitoring + +## Software Requirements + +- **Arduino IDE** 2.0 or later (recommended) or 1.8.x +- **Arduino Mbed OS Opta Boards** core +- Required Arduino libraries (detailed below) + +## Step 1: Install Arduino IDE + +If you don't already have Arduino IDE installed: + +1. Download Arduino IDE from [https://www.arduino.cc/en/software](https://www.arduino.cc/en/software) +2. Install for your operating system (Windows, macOS, or Linux) +3. Launch Arduino IDE + +## Step 2: Install Arduino Opta Board Support + +The Arduino Opta uses the Mbed OS core. You need to install board support: + +1. Open Arduino IDE +2. Go to **Tools → Board → Boards Manager** +3. In the search box, type: `Arduino Mbed OS Opta Boards` +4. Find **Arduino Mbed OS Opta Boards** in the list +5. Click **Install** (this may take several minutes) +6. Wait for installation to complete + +**Alternative using Boards Manager URL (if needed):** +1. Go to **File → Preferences** (or **Arduino IDE → Settings** on macOS) +2. In "Additional Boards Manager URLs", the Arduino Opta boards should already be included in the default Arduino index +3. Click **OK** +4. Follow steps 2-6 above + +## Step 3: Install Required Libraries + +The TankAlarm 112025 Client requires several libraries. Install them using the Library Manager: + +### Using Library Manager (Recommended) + +1. Go to **Tools → Manage Libraries** (or **Sketch → Include Library → Manage Libraries**) +2. Install each of the following libraries by searching for them and clicking **Install**: + +#### Required Libraries: + +| Library Name | Version | Purpose | +|--------------|---------|---------| +| **ArduinoJson** | 7.x or later | JSON parsing and serialization for configuration | +| **Blues Wireless Notecard** | Latest | Communication with Blues Notecard cellular module | +| **LittleFS** | Built-in with Mbed core | File system for persistent configuration storage | +| **Wire** | Built-in | I2C communication | + +#### Installing Each Library: + +**1. ArduinoJson** +- Search: `ArduinoJson` +- Install: `ArduinoJson by Benoit Blanchon` (version 7.x or later) +- Note: Version 7.x has breaking changes from v6, ensure you use v7+ + +**2. Blues Wireless Notecard** +- Search: `Notecard` +- Install: `Blues Wireless Notecard by Blues Inc.` +- This provides the Notecard.h interface + +**3. LittleFS** +- This is built into the Arduino Mbed OS core +- No separate installation required +- Included when you install Arduino Opta board support + +**4. Wire (I2C)** +- Built-in Arduino library +- No installation required + +#### Optional Libraries (for development/debugging): + +| Library Name | Purpose | +|--------------|---------| +| **IWatchdog** | Built-in watchdog timer (included with Mbed core) | + +### Verifying Library Installation + +To verify libraries are installed: +1. Go to **Sketch → Include Library** +2. Check that you see: + - ArduinoJson + - Notecard +3. Go to **File → Examples** +4. You should see example sketches for ArduinoJson and Notecard + +## Step 4: Open the Client Sketch + +1. Download or clone this repository +2. Navigate to `TankAlarm-112025-Client-BluesOpta` folder +3. Open `TankAlarm-112025-Client-BluesOpta.ino` in Arduino IDE +4. The IDE will open the sketch in a new window + +## Step 5: Configure Board Settings + +Before uploading, configure the correct board: + +1. Connect your Arduino Opta to your computer via USB-C cable +2. Go to **Tools → Board → Arduino Mbed OS Opta Boards** +3. Select **Arduino Opta** +4. Go to **Tools → Port** +5. Select the port showing your Arduino Opta (e.g., COM3, /dev/ttyACM0, or similar) + +### Board Configuration Summary: +- **Board:** Arduino Opta +- **Core:** Arduino Mbed OS Opta Boards +- **Upload Method:** USB +- **Port:** Select the detected Opta device + +## Step 6: Configure the Sketch (Optional) + +The client uses LittleFS (internal flash storage) for configuration instead of SD cards. Default configuration will be created on first boot. + +**Initial Configuration (Advanced Users):** +- Configuration is stored in `/client_config.json` on the device's internal flash +- On first boot, default configuration is created +- You can update configuration remotely via the server web interface (recommended) +- Manual configuration via serial console is also supported + +**Product UID Configuration:** +- Ensure `PRODUCT_UID` is set correctly for your Blues Notehub project +- Find this in your Blues Notehub project settings +- Update at the top of the sketch if needed: + ```cpp + #define PRODUCT_UID "com.your-company.your-product:your-project" + ``` + +## Step 7: Compile the Sketch + +Before uploading, verify the sketch compiles: + +1. Click the **Verify** button (✓) in the toolbar +2. Wait for compilation to complete +3. Check the output console for any errors +4. If successful, you'll see "Done compiling" and memory usage statistics + +**Expected Memory Usage:** +- Flash: Typically 60-80% of available space +- RAM: Typically 40-60% of available space + +If you see compilation errors, refer to the **Troubleshooting** section below. + +## Step 8: Upload to Arduino Opta + +1. Ensure Arduino Opta is connected via USB +2. Click the **Upload** button (→) in the toolbar +3. Wait for upload to complete (progress shown in console) +4. On success, you'll see "Upload complete" + +**Note:** First upload may take longer as the bootloader initializes. + +## Step 9: Verify Operation + +1. Open **Tools → Serial Monitor** (or press Ctrl+Shift+M) +2. Set baud rate to **115200** +3. Press the **Reset** button on the Opta +4. You should see startup messages including: + - "TankAlarm 112025 Client - Blues Opta" + - "LittleFS initialized" + - "Notecard UID: dev:xxxxx..." + - Hardware requirements and pin assignments + - Initial sensor readings + +### Expected Serial Output: +``` +TankAlarm 112025 Client - Blues Opta +Initializing... +LittleFS initialized +Notecard UID: dev:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +Hardware Requirements: + Analog inputs needed: X + Required expansion: Arduino Opta Ext A0602 +Configuration loaded from flash +Starting main loop... +``` + +## Step 10: Configuration Setup + +### Option A: Configure via Server Web Interface (Recommended) + +If you have the TankAlarm 112025 Server running: + +1. Access the server web interface at `http:///` +2. Navigate to the configuration section +3. Select your client device from the dropdown +4. Update configuration settings: + - Site name and device label + - Tank configurations (ID, name, high/low alarms) + - Sample interval + - Server fleet name +5. Click **Send Config to Client** +6. Monitor the client serial console for "Configuration updated from server" + +### Option B: Default Configuration + +On first boot, the client creates a default configuration: +- Sample interval: 1800 seconds (30 minutes) +- Single tank: "Tank A" +- Default alarm thresholds +- Server fleet: "tankalarm-server" + +You can update this later via the server web interface. + +## Troubleshooting + +### Compilation Errors + +**Error: `ArduinoJson.h: No such file or directory`** +- Solution: Install ArduinoJson library via Library Manager (see Step 3) +- Ensure you have version 7.x or later + +**Error: `Notecard.h: No such file or directory`** +- Solution: Install Blues Wireless Notecard library via Library Manager +- Search for "Notecard" and install "Blues Wireless Notecard" + +**Error: `LittleFS.h: No such file or directory`** +- Solution: Ensure Arduino Mbed OS Opta Boards core is installed +- LittleFS is built into the Mbed core +- Go to Boards Manager and verify "Arduino Mbed OS Opta Boards" is installed + +**Error: Board not found or wrong architecture** +- Solution: Install "Arduino Mbed OS Opta Boards" from Boards Manager +- Select **Tools → Board → Arduino Mbed OS Opta Boards → Arduino Opta** + +**Error: Sketch too big** +- Solution: The sketch size is optimized for Opta +- Ensure you're compiling for Arduino Opta, not a different board +- Check that optimization settings are correct + +### Upload Errors + +**Error: Port not found** +- Ensure USB-C cable is connected +- Try a different USB cable (some cables are charge-only) +- Check Device Manager (Windows) or `ls /dev/tty*` (Linux/Mac) to verify device appears +- Press reset button on Opta and try upload again immediately + +**Error: Upload timeout** +- Press and hold the reset button on Opta +- Click Upload in Arduino IDE +- Release reset button when upload starts +- On Opta, the bootloader should respond within a few seconds + +**Error: Permission denied (Linux/Mac)** +- Add your user to the dialout group: `sudo usermod -a -G dialout $USER` +- Log out and log back in +- Or use sudo: `sudo arduino-cli upload ...` + +### Runtime Errors + +**Serial Monitor shows: "LittleFS init failed; halting"** +- Solution: The internal flash may need to be formatted +- Try re-uploading the sketch +- If persistent, the flash may be corrupted - contact support + +**Serial Monitor shows: "Failed to initialize Notecard"** +- Check that Blues Wireless for Opta module is properly seated +- Verify I2C connections +- Check that Notecard has valid SIM and is activated +- Verify PRODUCT_UID matches your Blues Notehub project + +**No output on Serial Monitor** +- Verify baud rate is set to **115200** +- Press reset button on Opta +- Try a different USB port +- Check that correct COM port is selected + +**Configuration not loading** +- On first boot, default config is created automatically +- Check serial console for config creation messages +- Use server web interface to push new configuration + +## Blues Notehub Setup + +The client requires a Blues Notehub account and proper fleet configuration: + +1. **Create Notehub Account**: [https://notehub.io](https://notehub.io) +2. **Create a Product**: Set up a product for your tank alarm system +3. **Note the Product UID**: Update in sketch if different from default +4. **Create Fleets**: + - Create a fleet named `tankalarm-clients` (or your preferred name) + - Assign this client Notecard to that fleet +5. **Provision Notecard**: Claim your Notecard into the product +6. **Server Setup**: Deploy the TankAlarm 112025 Server to receive data + +For detailed Blues Notehub setup, see: +- [FLEET_IMPLEMENTATION_SUMMARY.md](FLEET_IMPLEMENTATION_SUMMARY.md) +- [MIGRATION_GUIDE.md](MIGRATION_GUIDE.md) +- [Blues Notehub Documentation](https://dev.blues.io/notehub/notehub-walkthrough/) + +## Advanced Configuration + +### Custom Product UID + +Edit near the top of the `.ino` file: +```cpp +#define PRODUCT_UID "com.your-company.your-product:your-project" +``` + +### Adjusting Sample Intervals + +Via server web interface (recommended) or by editing the default config in code: +```cpp +// Default sample interval in seconds +gConfig.sampleSeconds = 1800; // 30 minutes +``` + +### Adding Additional Tanks + +Configure via the server web interface, which supports up to 8 tanks per client. + +## Additional Resources + +### Hardware Documentation +- [Arduino Opta Overview](https://docs.arduino.cc/hardware/opta) +- [Arduino Opta Ext A0602 Analog Expansion](https://store-usa.arduino.cc/products/opta-ext-a0602) +- [Blues Wireless for Opta](https://dev.blues.io/hardware/opta-notecarrier/) + +### Software Documentation +- [ArduinoJson Documentation](https://arduinojson.org/) +- [Blues Notecard Arduino Library](https://dev.blues.io/tools-and-sdks/firmware-libraries/arduino-library/) +- [Mbed OS LittleFS](https://os.mbed.com/docs/mbed-os/latest/apis/littlefs.html) + +### Project Documentation +- [Device-to-Device API](DEVICE_TO_DEVICE_API.md) +- [Fleet Implementation Summary](FLEET_IMPLEMENTATION_SUMMARY.md) +- [Migration Guide](MIGRATION_GUIDE.md) + +## Getting Help + +If you encounter issues: + +1. Check the serial monitor output at 115200 baud +2. Review the troubleshooting section above +3. Consult the Blues Wireless documentation at [dev.blues.io](https://dev.blues.io) +4. Check Arduino Opta documentation at [docs.arduino.cc/hardware/opta](https://docs.arduino.cc/hardware/opta) +5. Review GitHub issues in this repository +6. Post questions on the Arduino Forum or Blues Wireless forum + +## Next Steps + +After successful installation: + +1. Verify the client appears in Blues Notehub +2. Set up the TankAlarm 112025 Server to receive data +3. Configure client settings via server web interface +4. Connect sensors to the Opta analog inputs +5. Monitor serial console to verify sensor readings +6. Test alarm conditions and daily reports + +See [FLEET_IMPLEMENTATION_SUMMARY.md](FLEET_IMPLEMENTATION_SUMMARY.md) for complete system setup. diff --git a/TankAlarm-112025-Client-BluesOpta/README.md b/TankAlarm-112025-Client-BluesOpta/README.md new file mode 100644 index 0000000..ebbea25 --- /dev/null +++ b/TankAlarm-112025-Client-BluesOpta/README.md @@ -0,0 +1,209 @@ +# TankAlarm 112025 Client - Blues Opta + +Tank level monitoring client using Arduino Opta with Blues Wireless Notecard cellular connectivity. + +## Overview + +The TankAlarm 112025 Client monitors tank levels using analog sensors and reports data to a central server via Blues Wireless Notecard. Key features include: + +- **Cellular connectivity** via Blues Wireless Notecard +- **Multi-tank support** - Monitor up to 8 tanks per device +- **Configurable alarms** - High and low thresholds per tank +- **Remote configuration** - Update settings from server web interface +- **Persistent storage** - LittleFS internal flash (no SD card needed) +- **Fleet-based communication** - Simplified device-to-device routing +- **Watchdog protection** - Auto-recovery from hangs + +## Hardware + +- **Arduino Opta Lite** - Industrial controller with built-in connectivity +- **Blues Wireless for Opta** - Cellular Notecard carrier +- **Arduino Opta Ext A0602** - Analog expansion module for sensors +- Analog sensors compatible with 0-10V or 4-20mA inputs + +## Quick Start + +### 1. Hardware Setup +1. Install Blues Wireless for Opta carrier on Arduino Opta +2. Activate Notecard with Blues Wireless (see [blues.io](https://blues.io)) +3. Connect Arduino Opta Ext A0602 for analog inputs +4. Connect tank level sensors to analog inputs + +### 2. Software Setup +1. Install Arduino IDE 2.x or later +2. Install Arduino Mbed OS Opta Boards core via Boards Manager +3. Install required libraries: + - **ArduinoJson** (version 7.x or later) + - **Blues Wireless Notecard** (latest) + - LittleFS (built into Mbed core) +4. Open `TankAlarm-112025-Client-BluesOpta.ino` in Arduino IDE +5. Update `PRODUCT_UID` to match your Blues Notehub project +6. Compile and upload to Arduino Opta + +**For detailed step-by-step instructions, see [INSTALLATION.md](INSTALLATION.md)** + +### 3. Blues Notehub Setup +1. Create account at [notehub.io](https://notehub.io) +2. Create a product for your tank alarm system +3. Create fleet named `tankalarm-clients` +4. Assign client Notecards to the client fleet +5. Claim your Notecard into the product + +### 4. Configuration +The client creates a default configuration on first boot. You can update configuration: + +**Via Server Web Interface (Recommended):** +1. Deploy the TankAlarm 112025 Server +2. Access server dashboard at `http:///` +3. Select client from dropdown +4. Update settings (site name, tanks, thresholds, etc.) +5. Click "Send Config to Client" + +**Default Configuration:** +- Sample interval: 1800 seconds (30 minutes) +- Single tank: "Tank A" +- High alarm: 110 inches +- Low alarm: 18 inches +- Server fleet: "tankalarm-server" + +## Configuration Fields + +### Basic Settings +- **Site Name**: Descriptive location (e.g., "North Tank Farm") +- **Device Label**: Short identifier (e.g., "Tank-01") +- **Server Fleet**: Fleet name for routing data (default: "tankalarm-server") + +### Sampling Settings +- **Sample Interval**: Seconds between sensor readings (default: 1800) +- **Level Change Threshold**: Inches of change to trigger telemetry (0 to disable) + +### Tank Configuration (per tank) +- **Tank ID**: Single letter identifier (A-H) +- **Tank Name**: Descriptive name +- **High Alarm**: Threshold in inches for high level alert +- **Low Alarm**: Threshold in inches for low level alert +- **Analog Pin**: Arduino Opta analog input (A0-A7, I1-I8) +- **Sensor Type**: "voltage" (0-10V) or "current" (4-20mA) +- **Min Value**: Minimum sensor value (e.g., 0.0V or 4.0mA) +- **Max Value**: Maximum sensor value (e.g., 10.0V or 20.0mA) +- **Min Inches**: Tank level in inches at minimum sensor value +- **Max Inches**: Tank level in inches at maximum sensor value + +## Operation + +### Normal Operation +1. Client wakes up at scheduled interval +2. Reads all configured tank sensors +3. Checks for alarm conditions (high/low thresholds) +4. Sends telemetry to server via Blues Notehub if: + - Alarm condition detected, OR + - Level changed by more than threshold, OR + - Daily report time reached +5. Sleeps until next sample interval + +### Alarm Handling +- High alarm: Tank level exceeds high threshold +- Low alarm: Tank level below low threshold +- Alarms sent immediately via Blues Notehub to server +- Server forwards alarms via SMS and/or email + +### Daily Reports +- Sent once per day regardless of level changes +- Default time: 7:00 AM (configurable on server) +- Includes all tank levels and status + +## Communication + +### Data Sent to Server +The client sends three types of notes via Blues Notehub: + +1. **Telemetry** (`telemetry.qi` to server fleet) + - Sent on level change or alarm + - Contains all tank levels and status + +2. **Alarms** (`alarm.qi` to server fleet) + - Immediate notification of threshold breach + - Includes tank ID, name, level, and threshold + +3. **Daily Reports** (`daily.qi` to server fleet) + - Once per day summary + - All tanks included + +### Configuration Received from Server +The client listens for configuration updates (`config.qi`): +- Pushed from server web interface +- Applied immediately on receipt +- Saved to LittleFS for persistence + +## Troubleshooting + +### No Serial Output +- Verify baud rate is 115200 +- Press reset button on Opta +- Check USB cable and connection + +### Notecard Not Connecting +- Verify Notecard is activated with Blues Wireless +- Check PRODUCT_UID matches Blues Notehub project +- Verify SIM card is installed and activated +- Check cellular coverage in deployment location + +### Configuration Not Loading +- Default config is created automatically on first boot +- Check serial console for config messages +- Use server web interface to push new config +- Verify server fleet name matches + +### Sensor Readings Incorrect +- Check analog input connections +- Verify sensor type (voltage vs current) +- Confirm min/max calibration values +- Check sensor power supply + +### Cannot Update from Server +- Verify client UID is correct in server interface +- Check that client and server are in correct fleets +- Confirm Blues Notehub shows note traffic +- Verify client is online and syncing + +## Development + +### Serial Console Commands +Monitor at 115200 baud for diagnostic output: +- Startup sequence and hardware detection +- Configuration loading +- Sensor readings +- Notecard communication +- Alarm conditions + +### Memory Usage +- Flash: ~60-80% (varies with configuration) +- RAM: ~40-60% during operation +- LittleFS: <1KB for configuration file + +## Documentation + +- **[INSTALLATION.md](INSTALLATION.md)** - Complete setup guide with Arduino IDE and library installation +- **[FLEET_IMPLEMENTATION_SUMMARY.md](FLEET_IMPLEMENTATION_SUMMARY.md)** - Architecture and design details +- **[MIGRATION_GUIDE.md](MIGRATION_GUIDE.md)** - Upgrading from route-based to fleet-based setup +- **[DEVICE_TO_DEVICE_API.md](DEVICE_TO_DEVICE_API.md)** - Technical details on Blues Notecard communication + +## Additional Resources + +- [Arduino Opta Documentation](https://docs.arduino.cc/hardware/opta) +- [Blues Wireless Developer Portal](https://dev.blues.io) +- [ArduinoJson Documentation](https://arduinojson.org/) +- [TankAlarm 112025 Server](../TankAlarm-112025-Server-BluesOpta/) + +## Support + +For issues or questions: +1. Check [INSTALLATION.md](INSTALLATION.md) troubleshooting section +2. Review serial console output at 115200 baud +3. Verify Blues Notehub note traffic +4. Check GitHub issues in this repository +5. Consult Blues Wireless documentation + +## License + +See [LICENSE](../LICENSE) file in repository root. diff --git a/TankAlarm-112025-Server-BluesOpta/INSTALLATION.md b/TankAlarm-112025-Server-BluesOpta/INSTALLATION.md new file mode 100644 index 0000000..3735412 --- /dev/null +++ b/TankAlarm-112025-Server-BluesOpta/INSTALLATION.md @@ -0,0 +1,491 @@ +# TankAlarm-112025-Server-BluesOpta Installation Guide + +This guide walks you through setting up the Arduino IDE and installing the TankAlarm 112025 Server sketch on an Arduino Opta with Blues Wireless Notecard. + +## Hardware Requirements + +- **Arduino Opta Lite** - [Purchase Link](https://store-usa.arduino.cc/products/opta-lite) +- **Blues Wireless for Opta** - [Purchase Link](https://shop.blues.com/collections/accessories/products/wireless-for-opta) +- **Ethernet connection** - RJ45 cable for network connectivity +- **USB-C cable** for programming +- **Power supply** - 12-24V DC power for continuous operation + +## Software Requirements + +- **Arduino IDE** 2.0 or later (recommended) or 1.8.x +- **Arduino Mbed OS Opta Boards** core +- Required Arduino libraries (detailed below) + +## Step 1: Install Arduino IDE + +If you don't already have Arduino IDE installed: + +1. Download Arduino IDE from [https://www.arduino.cc/en/software](https://www.arduino.cc/en/software) +2. Install for your operating system (Windows, macOS, or Linux) +3. Launch Arduino IDE + +## Step 2: Install Arduino Opta Board Support + +The Arduino Opta uses the Mbed OS core. You need to install board support: + +1. Open Arduino IDE +2. Go to **Tools → Board → Boards Manager** +3. In the search box, type: `Arduino Mbed OS Opta Boards` +4. Find **Arduino Mbed OS Opta Boards** in the list +5. Click **Install** (this may take several minutes) +6. Wait for installation to complete + +**Alternative using Boards Manager URL (if needed):** +1. Go to **File → Preferences** (or **Arduino IDE → Settings** on macOS) +2. In "Additional Boards Manager URLs", the Arduino Opta boards should already be included in the default Arduino index +3. Click **OK** +4. Follow steps 2-6 above + +## Step 3: Install Required Libraries + +The TankAlarm 112025 Server requires several libraries. Install them using the Library Manager: + +### Using Library Manager (Recommended) + +1. Go to **Tools → Manage Libraries** (or **Sketch → Include Library → Manage Libraries**) +2. Install each of the following libraries by searching for them and clicking **Install**: + +#### Required Libraries: + +| Library Name | Version | Purpose | +|--------------|---------|---------| +| **ArduinoJson** | 7.x or later | JSON parsing and serialization for configuration and API | +| **Blues Wireless Notecard** | Latest | Communication with Blues Notecard cellular module | +| **Ethernet** | Built-in or latest | Network connectivity for web server | +| **LittleFS** | Built-in with Mbed core | File system for persistent configuration storage | +| **Wire** | Built-in | I2C communication | + +#### Installing Each Library: + +**1. ArduinoJson** +- Search: `ArduinoJson` +- Install: `ArduinoJson by Benoit Blanchon` (version 7.x or later) +- Note: Version 7.x has breaking changes from v6, ensure you use v7+ + +**2. Blues Wireless Notecard** +- Search: `Notecard` +- Install: `Blues Wireless Notecard by Blues Inc.` +- This provides the Notecard.h interface + +**3. Ethernet** +- Search: `Ethernet` +- Install: `Ethernet by Arduino` (built-in library, should already be available) +- Used for the web server and intranet dashboard + +**4. LittleFS** +- This is built into the Arduino Mbed OS core +- No separate installation required +- Included when you install Arduino Opta board support + +**5. Wire (I2C)** +- Built-in Arduino library +- No installation required + +#### Optional Libraries (for development/debugging): + +| Library Name | Purpose | +|--------------|---------| +| **IWatchdog** | Built-in watchdog timer (included with Mbed core) | + +### Verifying Library Installation + +To verify libraries are installed: +1. Go to **Sketch → Include Library** +2. Check that you see: + - ArduinoJson + - Ethernet + - Notecard +3. Go to **File → Examples** +4. You should see example sketches for ArduinoJson, Ethernet, and Notecard + +## Step 4: Open the Server Sketch + +1. Download or clone this repository +2. Navigate to `TankAlarm-112025-Server-BluesOpta` folder +3. Open `TankAlarm-112025-Server-BluesOpta.ino` in Arduino IDE +4. The IDE will open the sketch in a new window + +## Step 5: Configure Board Settings + +Before uploading, configure the correct board: + +1. Connect your Arduino Opta to your computer via USB-C cable +2. Go to **Tools → Board → Arduino Mbed OS Opta Boards** +3. Select **Arduino Opta** +4. Go to **Tools → Port** +5. Select the port showing your Arduino Opta (e.g., COM3, /dev/ttyACM0, or similar) + +### Board Configuration Summary: +- **Board:** Arduino Opta +- **Core:** Arduino Mbed OS Opta Boards +- **Upload Method:** USB +- **Port:** Select the detected Opta device + +## Step 6: Configure the Sketch + +The server uses LittleFS (internal flash storage) for configuration. You need to configure network and Blues settings: + +### Product UID Configuration + +Update the Product UID to match your Blues Notehub project: + +```cpp +#define SERVER_PRODUCT_UID "com.your-company.your-product:your-project" +``` + +Find your Product UID in your Blues Notehub project settings. + +### Network Configuration + +The server uses DHCP by default. For static IP configuration, edit the code if needed. + +### Initial Configuration + +On first boot, the server creates default configuration in `/server_config.json`: +- Server name: "Tank Alarm Server" +- Client fleet: "tankalarm-clients" +- Default phone numbers and email settings +- Daily report time: 7:00 AM local time + +You can modify these via the web interface after initial setup. + +## Step 7: Compile the Sketch + +Before uploading, verify the sketch compiles: + +1. Click the **Verify** button (✓) in the toolbar +2. Wait for compilation to complete +3. Check the output console for any errors +4. If successful, you'll see "Done compiling" and memory usage statistics + +**Expected Memory Usage:** +- Flash: Typically 70-85% of available space (server is larger than client) +- RAM: Typically 50-70% of available space + +If you see compilation errors, refer to the **Troubleshooting** section below. + +## Step 8: Upload to Arduino Opta + +1. Ensure Arduino Opta is connected via USB +2. Click the **Upload** button (→) in the toolbar +3. Wait for upload to complete (progress shown in console) +4. On success, you'll see "Upload complete" + +**Note:** First upload may take longer as the bootloader initializes. + +## Step 9: Connect Ethernet + +1. After upload completes, disconnect USB (or leave connected for debugging) +2. Connect RJ45 Ethernet cable to the Opta's Ethernet port +3. Ensure the cable is connected to your local network +4. Power the Opta with 12-24V DC power supply +5. The Opta will obtain an IP address via DHCP + +## Step 10: Verify Operation + +### Via Serial Monitor (if USB connected): + +1. Open **Tools → Serial Monitor** (or press Ctrl+Shift+M) +2. Set baud rate to **115200** +3. Press the **Reset** button on the Opta +4. You should see startup messages including: + - "TankAlarm 112025 Server - Blues Opta" + - "LittleFS initialized" + - "Notecard UID: dev:xxxxx..." + - "Ethernet connected" + - "IP address: xxx.xxx.xxx.xxx" + - "Server listening on port 80" + +### Expected Serial Output: +``` +TankAlarm 112025 Server - Blues Opta +Initializing... +LittleFS initialized +Configuration loaded from flash +Notecard UID: dev:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +Ethernet connected +IP address: 192.168.1.100 +MAC address: XX:XX:XX:XX:XX:XX +Server listening on port 80 +Storage: LittleFS internal flash for configuration +Polling for client data... +``` + +### Via Network: + +1. Note the IP address from serial monitor +2. From a computer on the same network, open a web browser +3. Navigate to `http:///` +4. You should see the Tank Alarm dashboard + +If you don't have serial monitor access: +- Check your router's DHCP client list for "Arduino Opta" +- Try common IP ranges: 192.168.1.x, 192.168.0.x, 10.0.0.x + +## Step 11: Access the Web Dashboard + +1. Open web browser on a device connected to the same network +2. Navigate to: `http:///` +3. The dashboard shows: + - Current tank levels from all clients + - Alarm status + - Last update times + - Configuration interface + +### Dashboard Features: +- **Real-time tank monitoring**: View levels from all connected clients +- **Alarm display**: See current and recent alarms +- **Client configuration**: Update client settings remotely +- **Daily reports**: Schedule and manage daily email reports +- **System status**: View server and client connectivity + +## Step 12: Configure Server Settings + +### Via Web Interface: + +1. Navigate to server dashboard +2. Scroll to "Server Configuration" section +3. Update settings: + - Server name + - Client fleet name (must match Notehub fleet) + - SMS phone numbers (primary, secondary, tertiary) + - Email recipients for daily reports + - Daily report time +4. Click **Save Configuration** + +### Via Serial Console (Advanced): + +Configuration can also be managed by editing the LittleFS JSON file, but web interface is recommended. + +## Troubleshooting + +### Compilation Errors + +**Error: `ArduinoJson.h: No such file or directory`** +- Solution: Install ArduinoJson library via Library Manager (see Step 3) +- Ensure you have version 7.x or later + +**Error: `Notecard.h: No such file or directory`** +- Solution: Install Blues Wireless Notecard library via Library Manager +- Search for "Notecard" and install "Blues Wireless Notecard" + +**Error: `LittleFS.h: No such file or directory`** +- Solution: Ensure Arduino Mbed OS Opta Boards core is installed +- LittleFS is built into the Mbed core +- Go to Boards Manager and verify "Arduino Mbed OS Opta Boards" is installed + +**Error: `Ethernet.h: No such file or directory`** +- Solution: Ethernet library should be built-in +- Try installing via Library Manager: search for "Ethernet by Arduino" + +**Error: Board not found or wrong architecture** +- Solution: Install "Arduino Mbed OS Opta Boards" from Boards Manager +- Select **Tools → Board → Arduino Mbed OS Opta Boards → Arduino Opta** + +**Error: Sketch too big** +- Solution: The server sketch is larger than the client +- Ensure you're compiling for Arduino Opta (sufficient flash memory) +- Check that optimization settings are correct + +### Upload Errors + +**Error: Port not found** +- Ensure USB-C cable is connected +- Try a different USB cable (some cables are charge-only) +- Check Device Manager (Windows) or `ls /dev/tty*` (Linux/Mac) to verify device appears +- Press reset button on Opta and try upload again immediately + +**Error: Upload timeout** +- Press and hold the reset button on Opta +- Click Upload in Arduino IDE +- Release reset button when upload starts +- On Opta, the bootloader should respond within a few seconds + +**Error: Permission denied (Linux/Mac)** +- Add your user to the dialout group: `sudo usermod -a -G dialout $USER` +- Log out and log back in +- Or use sudo: `sudo arduino-cli upload ...` + +### Runtime Errors + +**Serial Monitor shows: "LittleFS init failed; halting"** +- Solution: The internal flash may need to be formatted +- Try re-uploading the sketch +- If persistent, the flash may be corrupted - contact support + +**Serial Monitor shows: "Failed to initialize Notecard"** +- Check that Blues Wireless for Opta module is properly seated +- Verify I2C connections +- Check that Notecard has valid SIM and is activated +- Verify SERVER_PRODUCT_UID matches your Blues Notehub project + +**Serial Monitor shows: "Ethernet failed"** +- Verify Ethernet cable is properly connected +- Check that the cable is connected to a working network port +- Try a different Ethernet cable +- Verify the network has DHCP enabled +- Check for link lights on the Ethernet port + +**Cannot access web dashboard** +- Verify the IP address from serial monitor +- Ensure your computer is on the same network +- Check firewall settings (allow port 80) +- Try pinging the IP address +- Verify the Opta obtained an IP via DHCP + +**Web dashboard loads but shows no data** +- Clients may not have checked in yet (wait for sample interval) +- Verify clients are configured with correct server fleet name +- Check Blues Notehub for note traffic +- Verify fleet configuration in Notehub + +### Network Issues + +**DHCP not working** +- Check that your network has a DHCP server (usually your router) +- Try power cycling the Opta +- Check if the MAC address is blocked by network security + +**Cannot access from specific computer** +- Check if computer is on the same subnet +- Verify no firewall is blocking port 80 +- Try accessing from a different device +- Check for VPN or network isolation + +## Blues Notehub Setup + +The server requires Blues Notehub configuration to receive data from clients: + +1. **Create Notehub Account**: [https://notehub.io](https://notehub.io) +2. **Create a Product**: Set up a product for your tank alarm system +3. **Note the Product UID**: Update SERVER_PRODUCT_UID in sketch +4. **Create Fleets**: + - Create a fleet named `tankalarm-server` (or your preferred name) + - Create a fleet named `tankalarm-clients` + - Assign server Notecard to server fleet + - Assign client Notecards to client fleet +5. **Provision Notecard**: Claim your Notecards into the product + +For detailed Blues Notehub setup, see: +- [FLEET_SETUP.md](FLEET_SETUP.md) +- [SETUP.md](SETUP.md) (legacy route-based setup) +- [Blues Notehub Documentation](https://dev.blues.io/notehub/notehub-walkthrough/) + +## Client Configuration via Web Interface + +Once the server is running, you can configure clients remotely: + +1. Navigate to `http:///` +2. Scroll to "Update Client Config" section +3. Select client from dropdown (populated automatically from received telemetry) +4. Update configuration: + - Site name and device label + - Server fleet name + - Sample interval + - Level change threshold + - Tank configurations (ID, name, high/low alarms) +5. Click **Send Config to Client** +6. Configuration is pushed via Blues Notehub to the target client +7. Client will apply and save configuration on next sync + +### Configuration Fields: + +- **Site Name**: Descriptive location (e.g., "North Tank Farm") +- **Device Label**: Short identifier (e.g., "Tank-01") +- **Server Fleet**: Fleet name for routing data (e.g., "tankalarm-server") +- **Sample Interval**: Seconds between readings (e.g., 1800 for 30 minutes) +- **Level Change Threshold**: Inches of change to trigger telemetry (0 to disable) +- **Tanks**: Up to 8 tanks per client with individual settings + +## Advanced Configuration + +### Static IP Address + +To use a static IP instead of DHCP, modify the code: + +```cpp +// Add before Ethernet.begin() in setup(): +IPAddress ip(192, 168, 1, 100); +IPAddress dns(192, 168, 1, 1); +IPAddress gateway(192, 168, 1, 1); +IPAddress subnet(255, 255, 255, 0); +Ethernet.begin(mac, ip, dns, gateway, subnet); +``` + +### Changing Web Server Port + +Default is port 80. To change: + +```cpp +// Find this line and modify: +EthernetServer server(80); // Change 80 to desired port +``` + +### Customizing Daily Report Time + +Via web interface, or edit default config: + +```cpp +gServerConfig.dailyReportHour = 7; // 7 AM +gServerConfig.dailyReportMinute = 0; // On the hour +``` + +## Security Considerations + +The web interface is designed for **intranet use only**: + +- No authentication by default +- Should only be accessible on trusted local networks +- Do not expose port 80 to the internet +- Consider firewall rules to restrict access +- For internet access, implement authentication and HTTPS + +## Additional Resources + +### Hardware Documentation +- [Arduino Opta Overview](https://docs.arduino.cc/hardware/opta) +- [Arduino Opta Networking](https://docs.arduino.cc/tutorials/opta/getting-started#network) +- [Blues Wireless for Opta](https://dev.blues.io/hardware/opta-notecarrier/) + +### Software Documentation +- [ArduinoJson Documentation](https://arduinojson.org/) +- [Blues Notecard Arduino Library](https://dev.blues.io/tools-and-sdks/firmware-libraries/arduino-library/) +- [Arduino Ethernet Library](https://www.arduino.cc/reference/en/libraries/ethernet/) +- [Mbed OS LittleFS](https://os.mbed.com/docs/mbed-os/latest/apis/littlefs.html) + +### Project Documentation +- [Fleet Setup Guide](FLEET_SETUP.md) +- [Setup Guide (Legacy)](SETUP.md) +- [Website Preview](WEBSITE_PREVIEW.md) + +## Getting Help + +If you encounter issues: + +1. Check the serial monitor output at 115200 baud +2. Review the troubleshooting section above +3. Verify network connectivity (ping test) +4. Check Blues Notehub for note traffic +5. Consult the Blues Wireless documentation at [dev.blues.io](https://dev.blues.io) +6. Check Arduino Opta documentation at [docs.arduino.cc/hardware/opta](https://docs.arduino.cc/hardware/opta) +7. Review GitHub issues in this repository + +## Next Steps + +After successful installation: + +1. Verify the server appears in Blues Notehub +2. Configure server settings via web interface +3. Set up client devices (see Client Installation Guide) +4. Configure clients via server web interface +5. Test client connectivity and data flow +6. Configure SMS and email settings +7. Set up daily reporting schedule +8. Monitor dashboard for tank levels and alarms + +See [FLEET_SETUP.md](FLEET_SETUP.md) for complete fleet configuration and [../TankAlarm-112025-Client-BluesOpta/INSTALLATION.md](../TankAlarm-112025-Client-BluesOpta/INSTALLATION.md) for client setup. diff --git a/TankAlarm-112025-Server-BluesOpta/README.md b/TankAlarm-112025-Server-BluesOpta/README.md new file mode 100644 index 0000000..1bed0c0 --- /dev/null +++ b/TankAlarm-112025-Server-BluesOpta/README.md @@ -0,0 +1,347 @@ +# TankAlarm 112025 Server - Blues Opta + +Central data aggregation server for TankAlarm system using Arduino Opta with Blues Wireless Notecard and Ethernet connectivity. + +## Overview + +The TankAlarm 112025 Server receives tank level data from multiple clients, displays real-time status on a web dashboard, sends SMS/email alerts, and enables remote client configuration. Key features include: + +- **Web dashboard** - Real-time tank monitoring via Ethernet +- **Remote configuration** - Update clients from web interface +- **Alert distribution** - SMS and email notifications for alarms +- **Daily reports** - Scheduled email summaries +- **Fleet management** - Centralized control of multiple clients +- **Persistent storage** - LittleFS internal flash (no SD card needed) +- **Blues Notehub integration** - Cellular data aggregation + +## Hardware + +- **Arduino Opta Lite** - Industrial controller +- **Blues Wireless for Opta** - Cellular Notecard carrier +- **Ethernet connection** - RJ45 cable for network connectivity +- **12-24V DC power supply** - For continuous operation + +## Quick Start + +### 1. Hardware Setup +1. Install Blues Wireless for Opta carrier on Arduino Opta +2. Activate Notecard with Blues Wireless (see [blues.io](https://blues.io)) +3. Connect Ethernet cable to local network +4. Connect 12-24V DC power supply + +### 2. Software Setup +1. Install Arduino IDE 2.x or later +2. Install Arduino Mbed OS Opta Boards core via Boards Manager +3. Install required libraries: + - **ArduinoJson** (version 7.x or later) + - **Blues Wireless Notecard** (latest) + - **Ethernet** (built-in) + - LittleFS (built into Mbed core) +4. Open `TankAlarm-112025-Server-BluesOpta.ino` in Arduino IDE +5. Update `SERVER_PRODUCT_UID` to match your Blues Notehub project +6. Compile and upload to Arduino Opta + +**For detailed step-by-step instructions, see [INSTALLATION.md](INSTALLATION.md)** + +### 3. Blues Notehub Setup +1. Create account at [notehub.io](https://notehub.io) +2. Create a product for your tank alarm system +3. Create two fleets: + - `tankalarm-server` - For the server device + - `tankalarm-clients` - For all client devices +4. Assign server Notecard to server fleet +5. Assign client Notecards to client fleet +6. Claim all Notecards into the product + +**For detailed fleet setup, see [FLEET_SETUP.md](FLEET_SETUP.md)** + +### 4. Access Web Dashboard +1. Power on the server and wait for Ethernet connection +2. Check serial monitor (115200 baud) for IP address +3. From a computer on the same network, navigate to: `http:///` +4. The dashboard displays real-time tank levels from all clients + +## Web Dashboard Features + +### Real-Time Monitoring +- **Tank Levels**: Current levels from all connected clients +- **Alarm Status**: Visual indicators for high/low alarms +- **Last Update**: Timestamp of most recent data from each client +- **System Status**: Server and client connectivity + +### Client Configuration +Update client settings remotely via the dashboard: +- Site name and device label +- Server fleet name +- Sample interval and level change threshold +- Tank configurations (up to 8 per client) +- Individual tank alarms and calibration + +### Server Configuration +Configure server behavior: +- Server name +- Client fleet name (for routing) +- SMS phone numbers (primary, secondary, tertiary) +- Email recipients for daily reports +- Daily report schedule (time of day) + +### API Endpoints + +The server exposes a simple REST API: + +- `GET /` - Web dashboard (HTML) +- `GET /api/status` - JSON status of all clients and tanks +- `POST /api/config` - Push configuration to a specific client + +Example: Push config to client +```bash +curl -X POST http://server-ip/api/config \ + -H "Content-Type: application/json" \ + -d '{ + "client": "dev:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", + "config": { + "sampleSeconds": 1800, + "tanks": [ + { + "id": "A", + "name": "North Tank", + "highAlarm": 110.0, + "lowAlarm": 18.0 + } + ] + } + }' +``` + +## Configuration + +### Server Configuration + +Stored in `/server_config.json` on LittleFS. Default values: + +```json +{ + "serverName": "Tank Alarm Server", + "clientFleet": "tankalarm-clients", + "smsPrimary": "+12223334444", + "smsSecondary": "+15556667777", + "smsTertiary": "", + "emailPrimary": "alerts@example.com", + "emailSecondary": "", + "dailyReportHour": 7, + "dailyReportMinute": 0 +} +``` + +### Client Configuration Cache + +The server caches configuration for each client in `/client_configs/.json`. This allows the dashboard to display current client settings. + +## Operation + +### Data Flow + +1. **Clients → Server**: + - Clients send telemetry, alarms, and daily reports + - Data routed via Blues Notehub using fleet targeting + - Server receives notes in `.qi` inbox files + +2. **Server Processing**: + - Polls Notecard for incoming notes every 5 seconds + - Processes telemetry to update dashboard + - Handles alarms and triggers SMS/email + - Aggregates daily reports + +3. **Server → Clients**: + - Configuration updates pushed from web interface + - Routed via Blues Notehub using device-specific targeting + - Clients receive and apply configuration immediately + +### Alert Processing + +When an alarm is received: +1. Server detects alarm in incoming `alarm.qi` note +2. Composes SMS message with tank details +3. Queues SMS for delivery via Blues Notehub +4. Updates dashboard to show alarm status +5. Logs alarm in system memory + +### Daily Reports + +The server generates daily reports: +1. Aggregates data from all clients at scheduled time +2. Formats email with current levels and changes +3. Queues email for delivery via Blues Notehub +4. Includes alarm history and status summary + +## Communication + +### Notes Received from Clients + +1. **Telemetry** (`telemetry.qi`) + - Tank levels and sensor data + - Timestamp and client identifier + - Used to update dashboard + +2. **Alarms** (`alarm.qi`) + - Immediate notification of threshold breach + - Tank ID, name, level, threshold + - Triggers SMS/email alerts + +3. **Daily Reports** (`daily.qi`) + - Once per day summary + - All tanks and status + - Used for email reporting + +### Notes Sent to Clients + +1. **Configuration** (`config.qi`) + - Pushed from web interface + - Device-specific targeting: `device::config.qi` + - Contains updated settings for client + +2. **SMS Requests** (`sms.qo`) + - Outbound SMS via Blues Notehub integration + - Can be routed to Twilio or other SMS provider + +3. **Email Requests** (`email.qo`) + - Outbound email via Blues Notehub integration + - Can be routed to SendGrid or other email provider + +## Troubleshooting + +### Cannot Access Dashboard + +**Check Network Connection:** +- Verify Ethernet cable is connected +- Check link lights on Ethernet port +- Ensure server obtained IP via DHCP +- Check serial monitor for IP address + +**Check Firewall:** +- Allow port 80 through firewall +- Verify computer is on same network/subnet +- Try accessing from different device + +**Check Server Status:** +- Serial monitor should show "Server listening on port 80" +- Try pinging the IP address +- Verify power supply is adequate + +### Dashboard Shows No Data + +**Verify Client Communication:** +- Check that clients have checked in (sample interval) +- Verify fleet configuration in Blues Notehub +- Check Blues Notehub Events for note traffic +- Confirm clients are configured with correct server fleet + +**Check Server Processing:** +- Serial monitor shows "Polling for client data..." +- Verify Notecard is connected and syncing +- Check that server is in correct fleet + +### Cannot Update Client Config + +**Verify Client UID:** +- Copy UID directly from Blues Notehub device page +- Format: `dev:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` +- Check for typos or truncation + +**Check Notehub Configuration:** +- Verify client is assigned to correct fleet +- Check that client is online and syncing +- Review Events for config note delivery + +**Check Network:** +- Ensure server can communicate with Notecard +- Verify I2C connection to Notecard +- Check serial monitor for error messages + +### SMS/Email Not Sending + +**Configure Downstream Routes:** +- SMS and email require additional Blues Notehub routes +- Route `sms.qo` to Twilio or SMS provider +- Route `email.qo` to SendGrid or email provider +- See Blues Notehub documentation for route setup + +**Verify Phone Numbers/Emails:** +- Check format in server configuration +- Phone: +1XXXXXXXXXX format +- Email: valid email addresses +- Test with known good numbers/addresses + +## Development + +### Serial Console Output +Monitor at 115200 baud for diagnostic information: +- Server startup and IP assignment +- Notecard connection status +- Incoming note processing +- Configuration updates +- Alarm processing +- Error messages + +### Memory Usage +- Flash: ~70-85% (server is larger than client) +- RAM: ~50-70% during operation +- LittleFS: <5KB for all configuration files + +### Network Configuration + +**Default: DHCP** +The server obtains an IP address automatically. + +**Static IP (if needed):** +Modify the code before `Ethernet.begin()`: +```cpp +IPAddress ip(192, 168, 1, 100); +IPAddress dns(192, 168, 1, 1); +IPAddress gateway(192, 168, 1, 1); +IPAddress subnet(255, 255, 255, 0); +Ethernet.begin(mac, ip, dns, gateway, subnet); +``` + +## Security Considerations + +**Intranet Use Only:** +- Web dashboard has no authentication +- Designed for trusted local networks only +- Do not expose port 80 to internet +- Use firewall rules to restrict access + +**For Internet Access:** +- Implement authentication (not included) +- Use HTTPS with valid certificates +- Consider VPN for remote access +- Add rate limiting and input validation + +## Documentation + +- **[INSTALLATION.md](INSTALLATION.md)** - Complete setup guide with Arduino IDE and library installation +- **[FLEET_SETUP.md](FLEET_SETUP.md)** - Simplified fleet-based configuration +- **[SETUP.md](SETUP.md)** - Legacy route-based setup (deprecated) +- **[WEBSITE_PREVIEW.md](WEBSITE_PREVIEW.md)** - Dashboard features and screenshots + +## Additional Resources + +- [Arduino Opta Documentation](https://docs.arduino.cc/hardware/opta) +- [Blues Wireless Developer Portal](https://dev.blues.io) +- [ArduinoJson Documentation](https://arduinojson.org/) +- [Arduino Ethernet Library](https://www.arduino.cc/reference/en/libraries/ethernet/) +- [TankAlarm 112025 Client](../TankAlarm-112025-Client-BluesOpta/) + +## Support + +For issues or questions: +1. Check [INSTALLATION.md](INSTALLATION.md) troubleshooting section +2. Review serial console output at 115200 baud +3. Verify network connectivity (ping test) +4. Check Blues Notehub note traffic +5. Consult Blues Wireless documentation +6. Check GitHub issues in this repository + +## License + +See [LICENSE](../LICENSE) file in repository root.