MqttSession Directory Reference

Directories
	dart
	java
	kotlin
	objc
	swift

Detailed Description

This directory contains comprehensive usage examples for the MqttSession module across all supported platforms.

Overview

The MqttSession module provides MQTT connectivity for publishing position data to MQTT brokers, including:

• MQTT broker connection management
• Position data publishing
• Connection state monitoring via listeners
• Multiple listener support
• Automatic device ID appending to topics

Covered Classes and Methods

MqttSession

• connect(server, port, subTopic, username, password) - Connect to MQTT broker and start publishing position data
• disconnect() - Disconnect from MQTT broker and stop publishing
• addListener(MqttSessionListener) - Add listener for connection state changes
• removeListener(MqttSessionListener) - Remove listener

MqttSessionListener

• onConnected() - Called when MQTT session successfully connects to the broker
• onError(Error) - Called when MQTT connection fails or is lost

Platform-Specific Examples

Java

• File: java/MqttSessionExample.java
• Features: Full MqttSession functionality with comprehensive error handling
• Usage: Run with javac MqttSessionExample.java && java MqttSessionExample

Kotlin

• File: kotlin/MqttSessionExample.kt
• Features: Kotlin-specific syntax with null safety and modern language features
• Usage: Run with kotlinc MqttSessionExample.kt -include-runtime -d MqttSessionExample.jar && java -jar MqttSessionExample.jar

Objective-C

• File: objc/MqttSessionExample.m
• Features: Objective-C implementation with proper memory management
• Usage: Compile with Xcode or command line tools

Swift

• File: swift/MqttSessionExample.swift
• Features: Swift implementation with optionals and modern syntax
• Usage: Run with swift MqttSessionExample.swift

Dart/Flutter

• File: dart/mqtt_session_example.dart
• Features: Dart implementation with async/await support
• Usage: Run with dart mqtt_session_example.dart

Key Features Demonstrated

1. Basic MQTT Connection

• SDK initialization with NavigationManager
• MqttSession creation
• Connection to MQTT broker with authentication
• Connection state monitoring

2. Connection Configuration

• Different port configurations (1883 for non-SSL, 8883 for SSL)
• Sub-topic configuration (final topic: "navigine/mobile/positions/" + subTopic + "/" + deviceId)
• Sub-topic validation (must not be empty and must not contain slashes)
• Username and password authentication

3. Listener Management

• Adding multiple listeners
• Removing listeners
• Connection state callbacks
• Error handling callbacks

4. Position Data Publishing

• Automatic position data publishing when connected
• Final topic format: "navigine/mobile/positions/" + subTopic + "/" + deviceId
• JSON payload format with position information

Configuration

All examples use the following configuration:

• Server URL: https://custom.navigine.com
• User Hash: USER-HASH-HERE (replace with actual hash)
• MQTT Server: mqtt.example.com (replace with actual MQTT broker)
• MQTT Port: 1883 (default) or 8883 (SSL)
• MQTT Sub-Topic: location1 (final topic will be "navigine/mobile/positions/location1/{deviceId}")
• MQTT Username: username (replace with actual username)
• MQTT Password: password (replace with actual password)

Topic Format

The MqttSession creates the final topic using the following template:

• Final topic: "navigine/mobile/positions/" + subTopic + "/" + deviceId
• Example: If subTopic is "location1" and deviceId is "device123", final topic will be "navigine/mobile/positions/location1/device123"

Sub-Topic Validation

The subTopic parameter is validated:

• Must not be empty
• Must match pattern [0-9a-zA-Z_-]+ (letters, digits, hyphens, and underscores only)
• Valid examples: "location1", "building-a", "floor_2", "abc123", "test-123_abc"
• Invalid examples: "", "building/a", "test@123", "location.1", "test space"

Error Handling

Examples include comprehensive error handling for:

• SDK initialization failures
• MQTT connection failures
• Connection lost events
• Authentication errors
• Network connectivity issues

Threading and Concurrency

• Java/Kotlin: Uses Thread.sleep() for timing
• Objective-C: Uses NSThread sleepForTimeInterval
• Swift: Uses Thread.sleep(forTimeInterval:)
• Dart: Uses Future.delayed() for async operations

Memory Management

• Java/Kotlin: Automatic garbage collection
• Objective-C: ARC (Automatic Reference Counting)
• Swift: ARC with strong/weak references
• Dart: Automatic memory management

Integration Notes

NavigationManager Integration

MqttSession requires NavigationManager to be initialized:

1. Get LocationManager from SDK
2. Get NavigationManager using LocationManager
3. Create MqttSession using NavigationManager

Position Data Publishing

When connected, MqttSession automatically publishes position data from NavigationManager:

• Position updates are published as JSON
• Payload includes: device_id, x, y, time, location_id, sublocation_id, type
• Publishing happens automatically when position updates are available

Listener Pattern

Examples show proper implementation of the observer pattern:

• Adding listeners for connection state updates
• Handling connection and error events in callbacks
• Proper cleanup of listeners

Usage Instructions

1. Setup: Replace USER-HASH-HERE with your actual user hash
2. MQTT Broker: Configure MQTT broker hostname, port, username, and password
3. Sub-Topic: Set appropriate MQTT sub-topic (must not be empty and must not contain slashes)
4. NavigationManager: Ensure NavigationManager is properly initialized
5. Run: Execute the example for your target platform
6. Monitor: Watch console output for connection events and position publishing

Dependencies

All examples require the Navigine SDK to be properly installed and configured for each platform:

• Java/Kotlin: Navigine SDK JAR files
• Objective-C/Swift: Navigine SDK framework
• Dart: Navigine SDK package

Troubleshooting

Common issues and solutions:

• SDK not initialized: Check user hash and server URL
• MQTT connection failed: Verify MQTT broker hostname, port, username, and password
• Invalid subTopic error: Ensure subTopic is not empty and does not contain slashes
• No position data published: Ensure NavigationManager is initialized and position updates are available
• Memory leaks: Ensure proper listener cleanup
• Compilation errors: Verify SDK installation and imports

Next Steps

After understanding these examples, you can:

• Implement custom MQTT topic structures
• Add position filtering before publishing
• Implement reconnection logic
• Add QoS level configuration
• Integrate with custom MQTT brokers
• Add message queuing for offline scenarios

Support

For additional help:

• Navigine SDK documentation
• Platform-specific development guides
• API reference documentation
• Community forums and support channels