# arduino-libraries/mkrnb architecture

> Architecture diagram of the GitHub repository arduino-libraries/mkrnb, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arduino-libraries/mkrnb
- Repository: https://github.com/arduino-libraries/mkrnb

## Overview

##### Project type and purpose
- This is an Arduino library (“MKRNB”) that provides a high-level C++ API for the MKR NB 1500 board to communicate over NarrowBand IoT (NB-IoT) or LTE Cat M1 networks.
- It is not a standalone application but a reusable connectivity library with example sketches showing how to use its public APIs.

##### File structure
- Top-level directories:
- src/              ← library implementation (C++ classes)
- examples/         ← Arduino sketches demonstrating library use cases
- docs/             ← detailed API documentation and usage guides
- .github/          ← CI workflows (compile examples, spell check, etc.)
- Key source files in src/:
- NBModem.*         ← core AT-command modem interface
- NBClient.*, NBSSLClient.* ← TCP/SSL client implementations
- NBUdp.*           ← UDP datagram support
- NB_SMS.*          ← SMS send/receive
- NBScanner.*, NBPIN.* ← network scanning and SIM PIN management
- NBFileUtils.*     ← file/flash-based utilities
- utility/          ← root certificates and socket buffering
- Configuration: library.properties for Arduino IDE integration, keywords.txt for syntax highlighting.

##### README for additional insights
- Reinforces that the library abstracts NB-IoT / LTE Cat M1 connectivity behind a uniform API.
- Examples in README link to reference docs on arduino.cc.

##### Main components
a. User Application Layer
- Arduino Sketch (one of the examples or any user-written .ino)
b. Library Public API Layer
- High-level classes: GPRS, NB, NBClient, NBSSLClient, NBUdp, NB_SMS, NBScanner, NBPIN
c. Core Modem Interface Layer
- NBModem: translates method calls into AT commands over serial/UART
- Modem.cpp / Modem.h: shared low-level communication routines
d. Hardware Abstraction / Board Layer
- SAMD21 MCU (runs Arduino core)
- u-blox SARA R4/N4 modem chip (handles radio protocols)
e. Network Layer
- Cellular network (NB-IoT or LTE Cat M1)
f. External Services
- TCP/UDP servers (HTTP, MQTT, NTP servers, custom backends)
- SMSC for SMS send/receive
- TLS certificate authorities for SSL validation
g. Utility Components
- Root certificate store (utility/NBRootCerts.h)
- Socket buffer management (utility/NBSocketBuffer.*)

##### Relationships and interactions
- The Arduino sketch invokes public API methods (e.g., begin(), connect(), sendSMS()).
- Public API classes call into NBModem to issue AT commands via Serial1 (UART).
- NBModem sends/receives AT commands to/from the u-blox chip.
- The hardware modem transmits IP packets over the cellular network.
- Remote services respond over the same path, with data bubbled back up through NBModem → public API → user sketch.
- For SSL/TLS, NBSSLClient wraps NBClient and negotiates a secure channel using built-in certificates.

##### Architectural patterns and design principles
- Layered architecture: clear separation between user code, API, modem driver, hardware, network, and external services.
- Dependency inversion: high-level classes depend on an abstract modem interface rather than concrete wires.
- Single Responsibility: each class/module handles one aspect (e.g., SMS, UDP, SSL) of communication.
- Utility modules isolate common functionality (buffering, cert store).

##### Detailed but concise
- Every public API class or hardware element critical to connectivity is represented.
- Data flow from application code down to bits on the air and back.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "User Application Layer"
        direction TB
        Sketch["Arduino Sketches"]:::user
    end

    subgraph "Public API Layer"
        direction TB
        GPRS["GPRS"]:::user
        NB["NB"]:::user
        NBClient["NBClient"]:::user
        NBSSLClient["NBSSLClient"]:::user
        NBUdp["NBUdp"]:::user
        NB_SMS["NB_SMS"]:::user
        NBScanner["NBScanner"]:::user
        NBPIN["NBPIN"]:::user
        NBFileUtils["NBFileUtils"]:::user
    end

    subgraph "Core Modem Interface Layer"
        direction TB
        NBModem["NBModem"]:::internal
        Modem["Modem"]:::internal
    end

    subgraph "Utilities"
        direction TB
        NBRootCerts["NBRootCerts"]:::util
        NBSocketBuffer["NBSocketBuffer"]:::util
    end

    subgraph "Hardware Abstraction / Board"
        direction TB
        MCU["SAMD21 MCU"]:::hardware
        ModemChip["u-blox SARA R4/N4"]:::hardware
    end

    Network["Cellular Network"]:::network

    subgraph "External Services"
        direction TB
        HTTPServer["HTTP/MQTT Servers"]:::external
        SMSC["SMSC"]:::external
        CertAuth["Certificate Authorities"]:::external
    end

    %% Connections
    Sketch -->|"use"| NB
    Sketch -->|"use"| GPRS
    Sketch -->|"use"| NBClient
    Sketch -->|"use"| NBSSLClient
    Sketch -->|"use"| NBUdp
    Sketch -->|"use"| NB_SMS
    Sketch -->|"use"| NBScanner
    Sketch -->|"use"| NBPIN
    Sketch -->|"use"| NBFileUtils

    GPRS -->|"AT commands"| NBModem
    NB -->|"AT commands"| NBModem
    NBClient -->|"AT commands / TCP"| NBModem
    NBSSLClient -->|"wraps NBClient"| NBClient
    NBSSLClient -->|"secure setup"| NBModem
    NBUdp -->|"AT commands / UDP"| NBModem
    NB_SMS -->|"AT commands / SMS"| NBModem
    NBScanner -->|"AT commands / scan"| NBModem
    NBPIN -->|"AT commands / PIN"| NBModem
    NBFileUtils -->|"flash utils"| NBModem

    NBModem -->|"low-level comms"| Modem
    Modem -->|UART| MCU
    MCU -->|Serial1| ModemChip
    ModemChip -->|RF| Network
    Network -->|RF| ModemChip
    ModemChip -->|Serial1| MCU
    Modem -->|"data"| NBModem
    NBModem -->|responses| NB

    NBRootCerts -->|"cert store"| NBSSLClient
    NBSocketBuffer -->|"buffering"| NBModem
    NBSocketBuffer -->|"buffering"| NBClient

    Network -->|"IP"| HTTPServer
    Network -->|"SMS"| SMSC
    HTTPServer -->|"TLS validation"| CertAuth

    %% Click Events
    click Sketch "https://github.com/arduino-libraries/mkrnb/tree/master/examples/"
    click GPRS "https://github.com/arduino-libraries/mkrnb/blob/master/src/GPRS.h"
    click NB "https://github.com/arduino-libraries/mkrnb/blob/master/src/NB.h"
    click NBClient "https://github.com/arduino-libraries/mkrnb/blob/master/src/NBClient.h"
    click NBSSLClient "https://github.com/arduino-libraries/mkrnb/blob/master/src/NBSSLClient.h"
    click NBUdp "https://github.com/arduino-libraries/mkrnb/blob/master/src/NBUdp.h"
    click NB_SMS "https://github.com/arduino-libraries/mkrnb/blob/master/src/NB_SMS.h"
    click NBScanner "https://github.com/arduino-libraries/mkrnb/blob/master/src/NBScanner.h"
    click NBPIN "https://github.com/arduino-libraries/mkrnb/blob/master/src/NBPIN.h"
    click NBFileUtils "https://github.com/arduino-libraries/mkrnb/blob/master/src/NBFileUtils.h"
    click NBModem "https://github.com/arduino-libraries/mkrnb/blob/master/src/NBModem.h"
    click Modem "https://github.com/arduino-libraries/mkrnb/blob/master/src/Modem.h"
    click NBRootCerts "https://github.com/arduino-libraries/mkrnb/blob/master/src/utility/NBRootCerts.h"
    click NBSocketBuffer "https://github.com/arduino-libraries/mkrnb/blob/master/src/utility/NBSocketBuffer.h"

    %% Styles
    classDef user fill:#e0ffe0,stroke:#008000,color:#004000
    classDef internal fill:#e0f0ff,stroke:#0066cc,color:#004080
    classDef util fill:#f0f0f0,stroke:#666666,color:#333333
    classDef hardware fill:#f2f2f2,stroke:#999999,color:#666666
    classDef network fill:#fff2cc,stroke:#cc9900,color:#996600
    classDef external fill:#ffe6e6,stroke:#cc0000,color:#800000
```
