> For the complete documentation index, see [llms.txt](https://docs.efento.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.efento.io/nb-iot-loggers/integrations/efento-coap-loader.md).

# Efento CoAP Loader

## **Overview**

The **Efento CoAP Loader** is a lightweight integration component that connects Efento NB-IoT loggers with your software platform. Efento loggers communicate using **CoAP over UDP** with **Protobuf-encoded** payloads. The loader handles this layer for you. It runs a dedicated **CoAP server** that receives messages from loggers, decodes them, and forwards the data to your system as **JSON over a REST API (HTTP/HTTPS)**. Your platform doesn't need to implement CoAP or Protobuf.

#### **What the loader forwards**

Each message type is forwarded to a separate, configurable REST endpoint:

* **Measurements**: sensor readings with battery status and the reason for the transmission.
* **Configuration**: a snapshot of the settings currently stored on the logger, including any configuration errors it reported.
* **Device info**: firmware version, runtime diagnostics (battery voltage, MCU temperature, runtime errors) and cellular network details (e.g., cell ID, signal parameters, band, coverage level).
* **Extended configuration:** additional settings such as the sensor name and calibration data.

This lets your platform monitor both sensor data and device health.

#### **Remote configuration and commands**

Your platform can update a logger remotely. When it responds to a measurements request, it can include configuration parameters (e.g., measurement or transmission interval, rules, server settings) or commands (e.g., request device info, start a firmware update). The loader delivers them to the logger in the CoAP response.

#### **Time synchronisation**

The loader automatically answers time requests from loggers and includes the current time in its responses, so loggers keep an accurate clock without any action from your platform.

## Architecture & data flow

The CoAP Loader acts as an intermediary layer between Efento NB-IoT loggers and your application.

<figure><img src="https://740246929-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGPFUI36OraG706yJS7dJ%2Fuploads%2FmE5eT4DSJ7CuBsslxVoe%2Fimage.png?alt=media&amp;token=544ad350-34a9-43b6-8044-b744dc0ac270" alt=""><figcaption></figcaption></figure>

{% stepper %}
{% step %}

#### Logger transmission

The logger sends a message using CoAP over UDP, with a Protobuf-encoded payload. Depending on the message type, it can contain measurements, the current configuration, device info, the extended configuration, or a time request.
{% endstep %}

{% step %}

#### Processing by the loader

The loader identifies the message type based on the CoAP path. It then decodes the payload and converts it into a JSON message. Time requests are answered by the loader directly and are not forwarded to your application.
{% endstep %}

{% step %}

#### Forwarding to your application

The loader sends the JSON message to your application in an HTTP POST request. Each message type goes to its own endpoint, configured in *application.yml*. If an API token is configured on the logger, it is included in the *X-Api-Token* header.
{% endstep %}

{% step %}

#### Application response

Your application must respond with an HTTP **2xx** status code (preferably 201 Created) within **12 seconds**. The response can:

1. Only confirm that the data was received (empty body).
2. Confirm that the data was received and include configuration parameters or commands for the logger. This is supported only in the response to the **measurements** endpoint.
   {% endstep %}

{% step %}

#### Response to the logger

The loader converts the HTTP status code into a CoAP response code (e.g., 2xx → 2.01 Created), encodes any configuration in Protobuf, adds the current time, and sends the response back to the logger. If the logger does not receive a successful response in time, it treats the transmission as failed and sends the data again later.
{% endstep %}
{% endstepper %}

## Key benefits

**Protocol translation**\
The loader converts CoAP communication with Protobuf-encoded payloads into standard **REST API requests with JSON**. Your backend doesn't need to support CoAP, UDP or Protobuf.

**Two-way device management**\
Beyond measurements, the loader forwards logger configuration and device health data. It also delivers configuration and commands from your platform back to the logger and keeps the logger clock in sync automatically.

**Configuration validation**\
The loader checks configuration parameters before sending them to the logger. Invalid parameters are removed and logged, so incorrect values never reach the device.

**Simple deployment**\
The loader is a **single Java application (.jar)**. It runs on any machine with Java 8 or later that can receive UDP traffic from the internet. Incoming messages are displayed in the console in real time, which makes testing the integration quick and easy.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.efento.io/nb-iot-loggers/integrations/efento-coap-loader.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
