TECHNICAL DOCUMENTATION - OCTOPUS¶

1. OVERVIEW¶

The Octopus is a multifunction IoT device based on ESP32 that integrates multiple sensors and actuators for remote monitoring and control applications. The device includes GPS, RFID, PIR, relays, and secure MQTT communication.

2. SYSTEM ARCHITECTURE¶

2.1 Main Hardware¶

Microcontroller: ESP32
Display: LCD TFT 237x133 pixels
LEDs: 7 NeoPixel RGB LEDs for status indicators
Buttons: 3 physical buttons (A, B, C)
Battery: 2 Li-ion 18650 cells in parallel (5Ah total)

2.2 Integrated Modules¶

GPS: GPS module with serial communication
RFID: 2 UHF RFID readers (dual antennas)
PIR: Passive infrared motion sensor
Relays: 4 relays controlled via I2C
WiFi: 802.11n wireless connectivity

3. INITIALIZATION AND CONFIGURATION FLOW¶

3.4 Device Initial Configuration Process¶

To set up WiFi for the first time or reset configuration:

Press and hold the left (A) and right (C) buttons while powering on or rebooting the device.
The Octopus will create a WiFi network named Octopus (AP mode) and will display instructions on the screen to connect.
The device will show a message and a QR code to facilitate the connection. Scan the QR or manually connect to the Octopus WiFi network with password octopus123.
Open a browser and go to http://192.168.4.1 from your phone or PC.
Fill in the form with your WiFi network name and password. Important: the WiFi network must be 2.4GHz (5GHz is not supported).
Save the configuration. The device will reboot automatically and attempt to connect to the configured WiFi network.

If you need to reconfigure WiFi in the future, repeat the process by holding buttons A and C during boot.

3.1 Boot Sequence¶

1. Load stored preferences
2. Verify WiFi credentials
3. If no credentials → AP Mode
4. If credentials exist → Connect to WiFi network
5. Configure MQTT with TLS certificates
6. Obtain license from server
7. Initialize all modules
8. Start main loop

3.2 Access Point (AP) Mode¶

When the device has no WiFi credentials configured: - SSID: Octopus - Password: octopus123 - IP: 192.168.4.1 - Web Server: Port 80 - Page: HTML configuration form

3.3 WiFi Configuration¶

Endpoint: GET /config?username=SSID&password=PASSWORD
Storage: ESP32 Preferences (NVS)
Reboot: Automatic after saving credentials

4. LICENSING SYSTEM¶

4.1 License Verification¶

Endpoint: https://main.dzd5pzd1l3nl1.amplifyapp.com/api/devices/mac/{MAC}
Frequency: Every 10 seconds
Format: JSON with fields license and license_name

4.2 License States¶

No license: license = "", license_name = "no license"
Licensed: license = "LICENSE_ID", license_name = "LICENSE_NAME"
Error: Returns -1, keeps previous license

4.3 MQTT Topics per License¶

/license/{LICENSE_ID}/octopus/{MAC_ADDRESS}/in      # Incoming commands (relay control, or photo request)
/license/{LICENSE_ID}/octopus/{MAC_ADDRESS}/out     # Device status (periodic publication)
/license/{LICENSE_ID}/octopus/{MAC_ADDRESS}/event   # Events (buttons, PIR)

5. MQTT COMMUNICATION¶

5.1 Security Configuration¶

Broker: a8p6o8w3qii41-ats.iot.us-east-1.amazonaws.com
Port: 8883 (TLS)
Certificates:
AmazonRootCA1.pem
certificate.pem
sc.private.key
Client ID: Device MAC address

5.2 Publish Topics¶

5.2.1 Device Status (`/out`)¶

The device periodically publishes its status to /license/{LICENSE_ID}/octopus/{MAC_ADDRESS}/out with the following format:

{
  "mac": "MAC_ADDRESS",
  "latitude": "LAT",
  "longitude": "LON",
  "altitude": "ALT",
  "gps_accuracy": "ACCURACY",
  "hdop": "HDOP",
  "speed_kmh": "SPEED",
  "valid_location": "FIX_STATUS",
  "timestamp": "ISO8601_DATETIME",
  "battery_level": "PERCENTAGE",
  "battery_charging": "BOOLEAN",
  "battery_current": "CURRENT_A",
  "battery_voltage": "VOLTAGE_V",
  "battery_remaining_time": "HOURS",
  "battery_charging_time": "HOURS",
  "rfid": "RFID_DATA_ARRAY", // JSON array of detected RFID tags
  "parked": "BOOLEAN",
  "pir": "BOOLEAN",
  "relay0": "BOOLEAN",
  "relay1": "BOOLEAN",
  "relay2": "BOOLEAN",
  "relay3": "BOOLEAN"
}

Notes: - The rfid field is a JSON string with an array of EPC/PC/RSSI objects. - The parked field indicates whether the vehicle is parked (automatic detection). - Battery fields are calculated in real time and may include remaining/charging time estimates.

5.2.2 Events (`/event`)¶

Events (buttons, PIR, RFID, etc.) are published to /license/{LICENSE_ID}/octopus/{MAC_ADDRESS}/event:

{
  "event_key": "EVENT_TYPE", // E.g.: "button_a", "movement", "rfid_detected"
  "timestamp": "ISO8601_DATETIME",
  "latitude": "LAT",
  "longitude": "LON",
  "altitude": "ALT",
  "gps_accuracy": "ACCURACY",
  "mac": "MAC_ADDRESS"
}

5.3 Subscription Topics (`/in`)¶

The device listens for commands on /license/{LICENSE_ID}/octopus/{MAC_ADDRESS}/in. Example relay command:

{
  "type": "relay",
  "index": 0-3,
  "state": true|false
}

Other commands may be added in the future (e.g., reset, configuration, etc.).

6. BUTTON FEATURES¶

6.1 Button A (Hold 3s)¶

Function: Special configuration (event button_a)

6.2 Button B (Hold 3s)¶

Function: Secondary function (event button_b)

6.3 Button C (Hold 3s)¶

Function: Tertiary function (event button_c)

6.4 Combination A+C (Hold 3s)¶

Function: Restore default configuration
Action: Clears WiFi credentials and reboots device

7. MODULES AND SENSORS¶

7.1 GPS System¶

Hardware: GPS module
Pins: RX=36, TX=26
Baudrate: 115200 bps
Data: Latitude, longitude, altitude, speed, HDOP, fix status
Frequency: Continuous update
Parking Detection: Algorithm based on speed and distance (see parked field in JSON)

7.2 RFID System¶

Hardware: 2 UHF RFID readers
Pins:
Antenna 1: RX=13, TX=14
Antenna 2: RX=16, TX=17
Frequency: Polling every 200ms
Data: EPC, PC, RSSI
Format: JSON array of detected tags

7.3 PIR Sensor¶

Pin: GPIO 35
Timeout: 5 seconds between events
Event: movement (published to /event topic)
Debounce: Implemented to avoid false positives

7.4 Relay System¶

Hardware: 4-RELAY I2C module
Address: 0x73
Control: 4 independent relays (controlled via MQTT and locally)
States: ON/OFF with LED indicators
Communication: I2C (SDA=32, SCL=33)

8. BATTERY MONITORING¶

8.1 Battery Parameters¶

Max voltage: 4.2V per cell
Min voltage: 3.2V per cell
Capacity: 5000mAh (2x 2500mAh)
Charge current: 1320mA

8.2 Intelligent Calculations¶

Level: Based on voltage with linear mapping
Remaining time: Estimate based on current and capacity
Smoothing: Filters to stabilize readings

10. USER INTERFACE¶

10.1 LCD Screen¶

Resolution: 237x133 pixels
Regions: 7 information areas
Logo: Netsocs logo in the center
Information: Real-time status of all modules

10.2 Information Regions¶

Region 0: Power and battery status
Region 1: PIR sensor status
Region 2: GPS data and coordinates
Region 3: WiFi and license status
Region 4: Relay status
Region 5: RFID data and buttons
Region 6: Central logo

11. CONFIGURATION AND DEPLOYMENT¶

11.1 System Requirements¶

Framework: Arduino
Platform: ESP32
Libraries: FastLED, ArduinoJson, PubSubClient, ESPAsyncWebServer
Certificates: PEM files for MQTT TLS

11.2 Configuration Files¶

SPIFFS: Storage for certificates and HTML page
Preferences: WiFi credentials and configuration
platformio.ini: Dependencies and build configuration

11.3 Environment Variables¶

MQTT Server: Configured for AWS IoT Core
API Hub: Endpoint for license verification
Driver Hub: Endpoint for additional configuration

12. SECURITY CONSIDERATIONS¶

12.1 MQTT Communication¶

TLS 1.2: X.509 certificates
Authentication: Client certificates
Authorization: License-based

12.2 WiFi¶

AP Mode: Only for initial configuration
Credentials: Stored in secure NVS
Restore: Reset to default configuration function

12.3 Sensitive Data¶

Certificates: Stored in SPIFFS
Credentials: Encrypted in NVS
MAC Address: Unique device identifier

13. INSTALLATION AND BUILD¶

13.1 Prerequisites¶

PlatformIO IDE
Python 3.7+
Git

13.2 Installation Steps¶

# Clone the repository
git clone <repository-url>
cd firmware

# Install dependencies
pio lib install

# Build the project
pio run

# Upload to the device
pio run --target upload

# Monitor serial
pio device monitor

13.3 Certificate Setup¶

Place certificate and resource files in the data/ folder:
AmazonRootCA1.pem
certificate.pem
sc.private.key
page.html (WiFi configuration page)
logo.bmp (logo displayed on screen)
Upload all files to SPIFFS: pio run --target uploadfs

14. TROUBLESHOOTING¶

14.1 Common Issues¶

WiFi connection error: Check credentials and signal; in the top-right you can see the network name as well as the local IP if connected.
License error: The device is connected to Wi‑Fi but not associated with any Netsocs license; contact the sales or support team.
GPS no signal: The device is in a place with poor or no reception; as soon as triangulation is possible, the device will fix the position. No reboot or manipulation of the GPS module is needed.
RFID not detecting: If no RFID detection appears on the Octopus antennas, they may not be close enough (ideally under 2 meters). Supported protocol: EPCglobal UHF Class 1 Gen 2, ISO 18000-6C.

14.2 Logs and Debug¶

Serial Monitor: 115200 baud
LED indicators: Visual status of each module
LCD screen: Real-time information

15. MAINTENANCE¶

15.1 Updates¶

Firmware: Build and upload new code
Certificates: Replace PEM files when they expire
Configuration: Modify variables in code

15.2 Calibration¶

GPS: Adjust timeout and accuracy per application
RFID: Configure transmission power
PIR: Adjust sensitivity and timeout

Note: This documentation is based on the default Octopus firmware. For custom firmware support (adapted sensors, RS232 pull‑up, etc.), consult the Netsocs development team.