From 44147dc69f2e0a9b0a9b67c1365494ef432779ec Mon Sep 17 00:00:00 2001
From: XdoctorwhoZ <xavier.rodriguezalvarez@gmail.com>
Date: Sun, 23 Jun 2024 06:10:47 +0100
Subject: [PATCH] propose a v0 for a registers interface

---
 .../mqtt-panduza/interfaces/registers.md      | 98 +++++++++++++++++++
 1 file changed, 98 insertions(+)
 create mode 100644 content/docs/50_platform/specifications/mqtt-panduza/interfaces/registers.md

diff --git a/content/docs/50_platform/specifications/mqtt-panduza/interfaces/registers.md b/content/docs/50_platform/specifications/mqtt-panduza/interfaces/registers.md
new file mode 100644
index 0000000..da67c4a
--- /dev/null
+++ b/content/docs/50_platform/specifications/mqtt-panduza/interfaces/registers.md
@@ -0,0 +1,98 @@
+---
+title: "Registers"
+weight: 3
+icon: "list_alt"
+---
+
+A registers interface allow the user to control a register map with write and read operations.
+
+This document describes the specific attributes of registers interfaces.
+
+Please refer to [API interface](../core.md) to get a generic description of the interface mechanism.
+
+### `[PLATF_00015_00]` - Info
+
+```json
+{
+    "type": "registers",
+    "version": 0
+}
+```
+
+## Commands
+
+The command topic for this interface is as follow:
+
+To write a register
+
+```json
+{
+    "cmd": "w",
+    "index": 0,
+    "value": 42
+}
+```
+
+Index is the index of the register in its map, user will probably use address.
+In that case, convertion between index and address must be done with settings.base_address and settings.register_size
+
+```
+address(index) = base_address + (index x register_size)
+index(address) = (address - base_address) / register_size
+```
+
+To read 3 register from index 0
+
+```json
+{
+    "cmd": "r",
+    "index": 0,
+    "size": 3,
+}
+```
+
+## Attributes
+
+| Attribute name | Retain Topic |
+| :------------- | :----------: |
+| map            |     true     |
+| settings       |     true     |
+| commands       |     true     |
+
+### `[PLATF_00016_00]` - map
+
+This attribute contains a 2 json array:
+
+- 1 for the register map values 
+- 1 for their last reading millisecond timestamps (0 if never read)
+
+```json
+{
+    "values": [1,2,3],
+    "timestamps_ms": [0, 111111111, 0]
+}
+```
+
+### `[PLATF_00017_00]` - settings
+
+| Field name         |                Description                |
+| :----------------- | :---------------------------------------: |
+| base_address       |          Base address of the map          |
+| register_size      | size of a unique register (8, 16, 32, 64) |
+| number_of_register |         total number of register          |
+
+```json
+{
+    "base_address": 0,
+    "register_size": 8,
+    "number_of_register": 10
+}
+```
+
+## Changelog
+
+### Version 0
+
+- First Experimentations
+
+