Ayla MobMobile SDK - Native MQTT (nMQTT) Developer Guide

Component: iOS_AylaSDK & Android_AylaSDK › Native MQTT
SDK Version: iOS 10.0.0 · Android 10.0.0
Platforms: iOS 16.0+ (Swift / Objective-C) · Android API 28+ (Java)
Status: Public developer documentation

Table of Contents

1. Overview
2. Features
3. Design Goals
4. Collection of Metrics
5. Getting Started
6. Installation
7. Porting to Different Platforms
8. iOS & Android — Platform Classification
9. Quick Links
10. Sample APIs
11. License
12. Support
13. Glossary

1. Overview

1.1 Who this guide is for

This guide is for iOS and Android developers integrating real-time device data into an app built on the Ayla Mobile SDK. By the end of this guide, you should understand how nMQTT fits into the SDK session, how to observe connection state and publish datapoints, how to install the component on each platform, and where to find the underlying broker contract if you need to port the transport to another client platform.

1.2 What nMQTT is

Native MQTT (nMQTT) is the real-time device-data transport of the Ayla mobile SDKs. It maintains a persistent, TLS-secured MQTT 5 session between the mobile app and the Ayla cloud MQTT broker, so property (datapoint) updates flow bidirectionally the moment they occur — without the latency and battery cost of HTTP polling.

nMQTT is implemented natively on both iOS and Android, against the same broker contract: identical topic scheme, authentication endpoint, JSON envelope, TLS port, and QoS. The two implementations differ only in language, MQTT client library, and local credential storage. Section 8 classifies the source and maps the two side by side.

nMQTT is selected per device by the cloud. When a device's cloud record reports transport_type = "mqtt-native", the SDK marks it AylaDeviceTransportType.NMQTT and routes its datapoint reads and writes over the native MQTT session. Other transports (legacy MQTT/CMQTT, or HTTP) continue to use their existing paths, so nMQTT coexists with them in the same session.

1.3 How it's wired into the SDK

The transport is owned by AylaNMQTTManager on each platform — reachable from the session as AylaSessionManager.nmqttManager (iOS) or AylaSessionManager.getMqttManager() (Android). The SDK wires it up automatically on sign-in: it is created during session start, added as a device-manager listener, and started. Application code normally only publishes datapoints and observes connection state — it does not manage the transport's connect/subscribe/reconnect lifecycle directly.

1.4 End-to-end path through this guide

If you are integrating nMQTT for the first time, the sections below are ordered to match the work you'll actually do:

1. Confirm your app meets the platform prerequisites (Section 5.1).
2. Install the SDK dependency for your platform (Section 6).
3. Reach the manager and observe connection state (Section 5.2–5.3).
4. Publish datapoints through the high-level property API (Section 5.4).
5. Understand the lifecycle the SDK manages for you (Section 5.5).
6. If you need to port the transport to a new client platform, implement the broker contract in Section 7.

2. Features

3. Design Goals

Note: A deliberate current constraint is one OEM ID per user for all nMQTT devices on an account. The manager resolves a single OEM from the device list for the MQTT username and the get-property subscribe topic; per-device topics still carry each device's DSN. This is documented in the AylaNMQTTManager class notes as an extension point.

4. Collection of Metrics

nMQTT does not embed any third-party analytics or user-tracking. "Metrics" here means the operational and diagnostic signals the transport produces for observability and troubleshooting:

• Connection state. AylaNMQTTManager.connectionState (uninitialized | connecting | connected | disconnected) and isConnected, with state transitions delivered to AylaNMQTTManagerDelegate.mqttConnectionState(state:).
• Structured logging. All components log through the SDK log facility (AylaLogD / AylaLogE and related macros, backed by AylaLogManager), tagged per component. Connect triggers, auth fetch/refresh/retry, subscribe results, disconnect reason codes, and socket diagnostics are all logged.
• Subscribe summary. A per-session summary of subscribed / pending / failed topics is emitted so subscription health can be audited.
• Delivery correlation. Publishes are correlated to broker PUBACK by message ID; get-property requests are correlated to responses by request ID.

On iOS, log verbosity is governed by the SDK's own log level (the MQTT client's log level is derived from it via getMQTTLogtype()). On Android, the same diagnostics flow through AylaLog. In both cases, nMQTT emits operational signals only — there is no third-party user analytics inside the transport.

5. Getting Started

5.1 Prerequisites

Before you start, confirm you have:

• An Ayla account with at least one device whose cloud record reports transport_type = "mqtt-native".
• iOS: Xcode with iOS 16.0+ deployment target, CocoaPods, and use_frameworks! enabled in your Podfile.
• Android: Android Studio with compileSdk 35 / minSdk 28 (Android 9, Pie, and newer) available in your project.
• No broker host, port, or credentials to configure yourself — nMQTT obtains the broker host and JWT from the cloud at runtime (see Section 7.1).

In normal use you do not create nMQTT yourself — the SDK session owns it. The typical flow follows.

5.2 Reach the manager

// Swift
let nmqtt = sessionManager.nmqttManager   // AylaNMQTTManager
let state = nmqtt.connectionState         // "connected", "connecting", ...
let live = nmqtt.isConnected              // Bool

5.3 Observe connection state

// Swift
final class Monitor: AylaNMQTTManagerDelegate {
    func mqttConnectionState(state: AylaNMQTTConnectionState) {
        print("nMQTT is now \(state.rawValue)")
    }
}

nmqtt.delegate = monitor

Expected result: your delegate receives mqttConnectionState(state:) callbacks as the session moves through uninitialized → connecting → connected, and back to disconnected on network loss or sign-out.

5.4 Publish a datapoint (recommended path)

Prefer the high-level property API — AylaProperty routes writes to nMQTT automatically for NMQTT devices, so you rarely call the transport directly:

// Swift — high level; SDK picks the transport
property.createDatapoint(datapointParams) { datapoint, error in
    // For an NMQTT device this is delivered over the MQTT session
}

5.5 Lifecycle (managed by the SDK)

nmqtt.resume()    // start / resume when there are NMQTT devices
nmqtt.pause()     // disconnect, keep listener (app background / DS pause)
nmqtt.shutDown()  // disconnect, clear broker auth, remove listener (sign-out)

The session calls resume on start, pause on background/data-stream pause, and shutDown on teardown, so most apps never call these directly.

Expected result: you should not need to call resume(), pause(), or shutDown() from application code under normal use. If you find yourself calling them directly, confirm the session lifecycle isn't already handling the transition you're trying to make.

5.6 Android equivalents

// Android (Java)
AylaNMQTTManager nmqtt = sessionManager.getMqttManager();
boolean live = nmqtt.getConnectionStatus();

nmqtt.addConnectionListener(new AylaNMQTTConnection.ConnectionListener() {
    public void onConnected() { /* ... */ }
    public void OnDisconnected(Throwable t) { /* ... */ }
});

nmqtt.addMessageListener((topic, payload) -> { /* device update */ });

// Preferred: high-level property write routes to nMQTT for NMQTT devices
property.createDatapoint(value, dp -> {}, err -> {});

nmqtt.onResume();   // lifecycle — normally driven by the SDK session
nmqtt.onPause();
nmqtt.shutDown();

6. Installation

6.1 iOS (CocoaPods)

nMQTT ships inside the Ayla iOS SDK (iOS_AylaSDK) — there is no separate package to add. It lives in the SDK's default Shared subspec, which declares the MQTT client dependency:

# Podfile
platform :ios, '16.0'
use_frameworks!

target 'YourApp' do
  pod 'iOS_AylaSDK'  # nMQTT is in the default 'Shared' subspec
end

# iOS_AylaSDK.podspec (relevant lines)
s.name = "iOS_AylaSDK"
s.version = "10.0.0"
s.ios.deployment_target = '16.0'
s.swift_version = '5.0'
s.license = { :type => 'Commercial', :file => 'LICENSE' }

# Shared subspec pulls the MQTT 5 client:
shared.dependency 'CocoaMQTT/Core', '2.3.0'

Then run pod install and open the generated .xcworkspace.

Requirements: iOS 16.0+, CocoaPods, and use_frameworks!. No broker host, port, or credentials need to be configured by the app — nMQTT obtains the broker host and JWT from the cloud at runtime.

Expected result: pod install completes without dependency conflicts, and MQTT/NativeMQTT symbols (AylaNMQTTManager, AylaNMQTTManagerDelegate, AylaNMQTTConnectionState) are available after you open the .xcworkspace and build.

6.2 Android (Gradle)

On Android, nMQTT ships inside the Ayla Android SDK library module (package com.aylanetworks.aylasdk.mqtt). Add the SDK module to your app and ensure the MQTT 5 client is on the classpath:

// Android_AylaSDK/library/build.gradle
android {
    compileSdk 35
    defaultConfig {
        minSdk 28       // Android 9 (Pie) and newer
        targetSdk 35
        versionName "10.0.0"
    }
}

dependencies {
    // MQTT 5 client used by nMQTT:
    implementation 'com.hivemq:hivemq-mqtt-client:1.3.3'
    // ... plus the Ayla Android SDK library module
}

The SDK obtains broker host, port, and credentials from the cloud auth response at runtime — no manual broker configuration is required.

Expected result: the project syncs and builds with com.aylanetworks.aylasdk.mqtt.AylaNMQTTManager resolvable from your app module.

7. Porting to Different Platforms

The iOS and Android implementations are both clients of a platform-neutral broker contract. Anything that can speak MQTT 5 and call the Ayla auth endpoint can implement an equivalent transport (for example, Linux/embedded or desktop). Porting means re-implementing the client against the same three contracts.

7.1 Authentication contract

POST authn/v1/tokens
body:  { "cnf": { "clientId": "<appId>_<device-id>" } }
reply: { "jwtToken": "...", "brokerHost": "...", "user": { "uuid": "..." }, "expiresAt": <epoch?> }

MQTT username = "aya:jwt:<oemId>:<userUUID>"
MQTT clientId = "<appId>_<per-install-device-id>"
connect: TLS, port 8883, keepAlive 60s, QoS 1

7.2 Topic contract

7.3 Message-envelope contract

A compact, versioned JSON envelope (ver, id, src, type, prop.dps[]). Datapoints carry name (n), type (t), value (v), timestamp (ts), and optional metadata. Datapoint types: integer, string, boolean, decimal, message.

Because these three contracts are broker-defined rather than platform-specific, they serve as a reference specification for any port. The Android SDK is exactly such a port: the same topic scheme, aya:jwt:{oem}:{uuid} username, TLS-8883 / QoS-1 connection, and authn/v1/tokens auth — re-implemented in Java over the HiveMQ client, storing the token in SharedPreferences instead of the Keychain. Section 8 sets the two implementations side by side.

8. iOS & Android — Platform Classification

nMQTT exists as two native implementations that speak the identical broker contract. This section classifies the source of each and maps the equivalent types.

8.1 Shared contract (identical on both platforms)

• Topics: up/data/{oem}/{oemModel}/{dsn}, up/status/{oem}/{oemModel}/{dsn}, down/{oem}/USERID/{uuid} (get-property responses), down/{oem}/{dsn}/data (send datapoint / get-property request).
• aya:jwt:{oem}:USERUUID MQTT username; broker auth via POST authn/v1/tokens with body { cnf: { clientId } }.
• MQTT 5 over TLS on port 8883, QoS 1 for subscribe and publish; per-device transport selection via cloud transport_type = "mqtt-native".

8.2 Implementation comparison

8.3 Source classification

iOS — root: iOS_AylaSDK/iOS_AylaSDK/MQTT/

• NativeMQTT/AylaNMQTTManager.swift, AylaNMQTTConnection.swift, AylaNMQTTAuthService.swift, AylaNMQTTTopicManager.swift, AylaNMQTTConstants.swift
• NativeMQTT/Model/AylaNMQTTMessage.swift, AylaNMQTTAuthResponse.swift
• NativeMQTT/AylaNMQTTManagerListenerBridge.{h,m} (Objective-C device-manager bridge)

Android — root: Android_AylaSDK/library/src/main/java/com/aylanetworks/aylasdk/

• mqtt/AylaNMQTTManager.java, mqtt/AylaNMQTTConnection.java, mqtt/AylaNMQTTTopicManagement.java, mqtt/AylaNMQTTConstants.java
• AylaNMQTTAuthService.java (broker JWT auth)
• mqtt/NMQTTDataStream.java (payload model), mqtt/data/AylaNMQTTAuthToken.java, mqtt/data/AylaDSMqtt*.java (DSS filters)

9. Quick Links

Source and reference material in each SDK repository.

iOS — iOS_AylaSDK/iOS_AylaSDK/

Android — Android_AylaSDK/library/src/main/java/com/aylanetworks/aylasdk/

Repository:

• iOS SDK source: https://github.com/Ayla-Networks/iOS_AylaSDK

10. Sample APIs

Supported public surface of AylaNMQTTManager on each platform (other members are internal SDK use).

10.1 iOS — type & lifecycle

@objc public class AylaNMQTTManager: NSObject {
    public init(settings: AylaSystemSettings,
                deviceManager: AylaDeviceManager,
                httpClient: AylaHTTPClient?)

    public var connectionState: String   // uninitialized|connecting|connected|disconnected
    public var isConnected: Bool
    public weak var delegate: AylaNMQTTManagerDelegate?

    public func resume()
    public func pause()
    public func shutDown()
}

10.2 iOS — publishing

// Publish a datapoint to a device; completion fires on broker PUBACK.
public func publishDatapoint(withDsn dsn: String,
                              oemModel: String,
                              oemId: String,
                              propertyName: String,
                              value: Any?,
                              baseType: String,
                              completion: @escaping (AylaDatapoint?, NSError?) -> Void)

// Request current property state(s) over MQTT.
public func publishGetPropertyRequest(withPropertyNames propertyNames: [String]?,
                                       device: AylaDevice?,
                                       completion: ((NSError?) -> Void)?)

10.3 iOS — delegate

public protocol AylaNMQTTManagerDelegate: AnyObject {
    func mqttConnectionState(state: AylaNMQTTConnectionState)
}

public enum AylaNMQTTConnectionState: String {
    case uninitialized, connecting, connected, disconnected
}

10.4 iOS — Objective-C

AylaNMQTTManager *nmqtt = session.nmqttManager;
[nmqtt publishDatapointWithDsn:dsn
                       oemModel:oemModel
                          oemId:oemId
                   propertyName:name
                          value:value
                       baseType:baseType
                     completion:^(AylaDatapoint *dp, NSError *err) { /* ... */ }];

10.5 Android (Java)

public class AylaNMQTTManager
        implements AylaDeviceManager.DeviceManagerListener, ... {

    public AylaNMQTTManager(AylaSessionManager sessionManager,
                             AylaDeviceManager deviceManager)

    public void addConnectionListener(AylaNMQTTConnection.ConnectionListener l)
    public void addMessageListener(AylaNMQTTConnection.MessageListener l)
    public void addSubscribeListener(AylaNMQTTConnection.SubscriptionListener l)

    public boolean getConnectionStatus()
    public void onResume()
    public void onPause()
    public void disconnect()
    public void shutDown()

    // Publish a datapoint for an NMQTT device (routed here by AylaProperty).
    public void publishDataPoint(AylaDevice device, AylaProperty property,
                                  Object value, AylaNMQTTConnection.PublishListener listener)
}

11. License

Both the Ayla iOS SDK and the Ayla Android SDK, including the nMQTT component, are distributed under a commercial license. The LICENSE file in each repository states: "Copyright 2016 Ayla Networks, all rights reserved." The iOS podspec declares license = { :type => 'Commercial', :file => 'LICENSE' }.

This is proprietary software, not open source. Use is governed by your commercial agreement with Ayla Networks. Third-party dependencies (for example, CocoaMQTT on iOS and the HiveMQ MQTT client on Android) retain their own respective licenses.

12. Support

nMQTT is maintained by Ayla Networks as part of the iOS_AylaSDK and Android_AylaSDK. For integration help, broker/OEM configuration, or defect reports, contact your Ayla technical account representative or Ayla developer support, and reference the platform and SDK version (iOS 10.0.0 / Android 10.0.0) and the nMQTT component.

• iOS SDK source: https://github.com/Ayla-Networks/iOS_AylaSDK
• When reporting an issue, capture SDK logs (enable verbose logging) and the connection-state transitions around the event.

12.1 Troubleshooting

Start by capturing verbose SDK logs and the sequence of mqttConnectionState (iOS) or connection-listener (Android) transitions around the event, then check against the symptoms below.

13. Glossary