> 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/installation-and-setup.md).

# Installation and setup

## Prerequisites

Before you begin, ensure your environment meets the following requirements:

* **Java Runtime Environment (JRE)**\
  Version **8 or higher** must be installed on the machine running the loader.
* **Network access**\
  The machine running the CoAP Loader must be reachable from the public Internet. This requires either:
  * A **public IP address**, or
  * **Port forwarding** configured on your router.
* **Firewall configuration**\
  Ensure that the **CoAP port** (default: 5683, but can be customised) is open for **incoming UDP traffic**.
* **Custom application requirements**\
  Your application must:
  * Be reachable by the CoAP Loader over HTTP/HTTPS.
  * Accept **REST API requests with JSON payloads**.
  * Process measurement, configuration, and device information data sent by the loader.
  * Process incoming requests quickly and return a response without blocking or unnecessary delays. Sensors wait for a confirmation that the server has received the data; **longer response times increase battery consumption**, and if a response is not received in time, the sensor will assume the server is unavailable and retry transmission using a backoff timer.
  * Respond to requests sent by the CoAP Loader with an **HTTP 2xx status code** (preferably **201 Created**). Failure to return a successful response code may cause the loader to treat the request as unsuccessful.
  * Be capable of handling bursts of incoming sensor data. Sensors transmit measurements in batches, meaning a single message frame may contain **hundreds of measurements** that need to be parsed, processed, and stored efficiently without delaying the response to the loader.

## Installation and setup

{% stepper %}
{% step %}

### Download the CoAP Loader

You can download the latest version of the **Efento CoAP Loader** using the link below:

{% embed url="<https://drive.google.com/file/d/1Pr4ntDL-6CrMX6nAu33k4GA1pCqVqjPg/view?usp=sharing>" %}

Unzip it and save the files in a directory on the machine where the loader will be executed.
{% endstep %}

{% step %}

### Configuration

The loader is configured using the **`application.yml`** file located in the main directory of the application.

You must modify this file to match your infrastructure and define the endpoints where the data will be forwarded.

```yaml
# REST API Endpoints - where data will be forwarded
endpoint: "http://your-platform.com/api/measurements" # Replace with the endpoint address  
endpointConfiguration: "http://your-platform.com/api/config" # Replace with the endpoint address
endpointDeviceInfo: "http://your-platform.com/api/info" # Replace with the endpoint address

# Ports Settings
appPort: 8080   # Port on which the loader management interface runs
coapPort: 5683  # Port on which the loader listens for sensor messages
```

| Endpoint                | Purpose                                                         |
| ----------------------- | --------------------------------------------------------------- |
| `endpoint`              | Receives measurement data from sensors                          |
| `endpointConfiguration` | Receives sensors configuration                                  |
| `endpointDeviceInfo`    | Receives device metadata (technical parameters, firmware, etc.) |

{% hint style="warning" %}
All endpoints must accept **HTTP POST requests with JSON payloads**.
{% endhint %}
{% endstep %}

{% step %}

### Run the CoAP Loader

Open a **terminal or command prompt** and navigate to the folder in which the CoAP Loader files are located.

Run the application with the following command:

```
java -jar loader-coap-demo-X-X-X.jar
```

Replace **`X-X-X`** with the actual version number of your file.

Once started, the loader will begin listening for **incoming CoAP messages from sensors**.

{% hint style="warning" %}

## Important – Network Connectivity

* If the loader runs behind **NAT**, you must configure **port forwarding** on your router.
* Forward the **UDP port used for CoAP communication (default: 5683)** to the machine running the loader.
* Without a **public IP address** or **proper port forwarding**, sensors will not be able to deliver data to the loader.
  {% endhint %}
  {% endstep %}

{% step %}

### Connect sensors to the CoAP Loader

To start receiving data, you must manually configure each Efento sensor to send data to your CoAP Loader instance as described in "[Configuration with a custom server](/nb-iot-loggers/configuration-with-a-custom-server.md)" section.

Enter the following parameters:

* **Server Address -** the **public IP address or domain name** of the machine running the CoAP Loader
* **Port -** the **CoAP port** configured in `application.yml` (default: **5683**).
* Optionally you can configure the **Measurement interval** and the **Transmission interval**

After configuration, the sensor will begin transmitting measurements to the loader.

When the first message is received, it will be forwarded to the selected endpoint and appear in the **application console output**.
{% endstep %}
{% endstepper %}

## Verification & Troubleshooting

* **Console Output**: Incoming sensor measurements are displayed **in real time in the terminal** where the loader is running. This is the fastest way to verify that the sensors are sending data correctly.
* **Log Files**: The application automatically creates a log file (`log.log`). This file is stored in the **main application directory** and contains detailed diagnostic information useful for debugging connectivity or integration issues.
* **Platform Response**: Your application must return an **HTTP success status code (2xx)**.

  Recommended responses include: **201 Created, 200 OK, 204 No Content**

  If your platform returns a **non-2xx response**, the loader may treat the transmission as unsuccessful and log an error.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.