From 09882ba799cc919ba26a9e38fb8b444842fc1ce5 Mon Sep 17 00:00:00 2001 From: Amin Ben Romdhane Date: Tue, 18 Mar 2025 12:56:15 +0100 Subject: [PATCH] Update documentation --- README.md | 85 ++- docs/api/ubus/bbfdm.json | 93 +-- docs/api/ubus/bbfdm.md | 665 ++++-------------- docs/api/ubus/bbfdm_micro_service.json | 64 +- docs/api/ubus/bbfdm_micro_service.md | 307 +++----- docs/guide/bbfdmd.md | 219 +++--- docs/guide/dm-service.md | 250 +++++-- docs/guide/extend_datamodel.md | 45 ++ ...libbbfdm-api.md => libbbfdm-api-legacy.md} | 8 +- docs/guide/libbbfdm-api-version-2.md | 19 + docs/guide/libbbfdm-ubus.md | 207 +++--- tools/README.md | 2 +- 12 files changed, 778 insertions(+), 1186 deletions(-) create mode 100644 docs/guide/extend_datamodel.md rename docs/guide/{libbbfdm-api.md => libbbfdm-api-legacy.md} (95%) create mode 100644 docs/guide/libbbfdm-api-version-2.md diff --git a/README.md b/README.md index 5ef60a50..058e63ab 100644 --- a/README.md +++ b/README.md @@ -1,49 +1,51 @@ # BroadBand Forum Data Models (BBFDM) -`bbfdm` is a suite to provide TR181 datamodel backend for Higher layer management protocols like [TR-069/CWMP](https://cwmp-data-models.broadband-forum.org/) or [TR-369/USP](https://usp.technology/). It is designed in a hardware agnostic way and provides the available datamodel parameters over ubus on the northbound interface and creates the datamodel mapping based on uci and ubus on southbound interface. +`bbfdm` is a suite to provide a TR181 data model backend for higher-layer management protocols like [TR-069/CWMP](https://cwmp-data-models.broadband-forum.org/) or [TR-369/USP](https://usp.technology/). It is designed in a hardware-agnostic way and provides the available data model parameters over Ubus on the northbound interface and creates the data model mapping based on UCI and Ubus on the southbound interface. `bbfdm` has five main components: | Component | Description | | ------------ | ------------------------------------------------- | -| bbfdmd | A daemon to expose data model objects over ubus | -| dm-service | A daemon to expose data model objects as micro-service over ubus | -| libbbfdm-api | API library to create and parse datamodel tree | -| libbbfdm-ubus | API library to expose datamodel over ubus | -| libbbfdm | A static library that contains the core data model of TR181 | - +| bbfdmd | A daemon to expose data model objects over Ubus | +| dm-service | A daemon to expose data model objects as a microservice over Ubus | +| libbbfdm-api | API library to create and parse data model trees | +| libbbfdm-ubus | API library to expose data model over Ubus | +| libbbfdm | A shared library containing the core data model of TR181, running as a microservice | ## Directory Structure -`bbfdm` package is structured as follow: +`bbfdm` package is structured as follows: ```bash -├── bbfdmd -- This directory contains daemon code to expose the datamodel tree on northbound -│   └── ubus - Daemon to expose datamodel over ubus -├── dm-service -- This directory contains daemon code to expose the datamodel tree as micro-service -├── docs -- More detailed explanation of datamodel and user guide -├── gitlab-ci -- Used for CI/CD pipeline test -├── libbbfdm -- Minimal TR181 core datamodel implementation -├── libbbfdm-api -- API library to create datamodel definition and parse the datamodel definition to form a datamodel tree -├── libbbfdm-ubus -- API library to expose datamodel over ubus -├── tools -- Tools to convert xml datamodel definition to json, generate c code and many more -└── utilities -- Small helper utilities to complete/optimize the datamodel deployment +├── bbfdmd -- This directory contains daemon code to expose the data model tree on the northbound +│   └── ubus - Daemon to expose data model over Ubus +├── dm-service -- This directory contains daemon code to expose the data model tree as a microservice +├── docs -- More detailed explanation of the data model and user guide +├── gitlab-ci -- Used for CI/CD pipeline tests +├── libbbfdm -- Minimal TR181 core data model implementation +├── libbbfdm-api -- API library to create data model definitions and parse the data model definition to form a data model tree +│   └── legacy - Legacy version of `libbbfdm-api` containing APIs for creating and parsing data model definitions to build a data model tree +│   └── version-2 - New version of `libbbfdm-api` with a more flexible and generic implementation, making it easier to use in dm-service and unified daemon +├── libbbfdm-ubus -- API library to expose data model over Ubus +├── tools -- Tools to convert XML data model definitions to JSON, generate C code, and more +└── utilities -- Small helper utilities to complete/optimize the data model deployment ``` ## Important Topics * [BBFDMD Design](./docs/guide/bbfdmd.md) -* [Micro-Service Design](./docs/guide/dm-service.md) -* [LIBBBFDM-API Documentation](./docs/guide/libbbfdm-api.md) +* [Microservice Design](./docs/guide/dm-service.md) +* [LIBBBFDM-API/Legacy Documentation](./docs/guide/libbbfdm-api-legacy.md) +* [LIBBBFDM-API/Vesrion-2 Documentation](./docs/guide/libbbfdm-api-version-2.md) * [LIBBBFDM-UBUS Documentation](./docs/guide/libbbfdm-ubus.md) * [Utilities Documentation](./utilities/README.md) * [Tools](./tools/README.md) -* [How to extend datamodel with C Code](./docs/guide/How_to_extend_datamodel_with_C_Code.md) -* [How to extend datamodel with JSON](./docs/guide/How_to_extend_datamodel_with_JSON.md) +* [How to extend data model with C Code](./docs/guide/How_to_extend_datamodel_with_C_Code.md) +* [How to extend data model with JSON](./docs/guide/How_to_extend_datamodel_with_JSON.md) ## Good To Know -- The current data model implementation follows the latest version of the data model, version `2.18``. +- The current data model implementation follows the latest version of the data model, version `2.18`. - Instance alias handling has been moved to the icwmp repository since `bbfdm` repository only supports the common functionality provided by CWMP and USP protocols. @@ -52,28 +54,27 @@ - The data model implementation uses different directories to store temporary UCI configurations based on the protocol being used. The details are as follows: | Protocol | Save Config Directory | Config Directory | Save Dmmap Directory | Dmmap Directory | -| -------- | ------------------------ ---------------- | ---------------------- | ---------------- | +| -------- | ------------------------ | ---------------- | ---------------------- | ---------------- | | cwmp | /tmp/bbfdm/.cwmp/config | /etc/config | /tmp/bbfdm/.cwmp/dmmap | /etc/bbfdm/dmmap | | usp | /tmp/bbfdm/.usp/config | /etc/config | /tmp/bbfdm/.usp/dmmap | /etc/bbfdm/dmmap | | both | /tmp/bbfdm/.bbfdm/config | /etc/config | /tmp/bbfdm/.cwmp/dmmap | /etc/bbfdm/dmmap | - -### Compilation helper utilities +### Compilation Helper Utilities * [Readme](https://dev.iopsys.eu/feed/iopsys/-/blob/devel/bbfdm/README.md) -* [Compilation Helper utility](https://dev.iopsys.eu/feed/iopsys/-/blob/devel/bbfdm/bbfdm.mk) +* [Compilation Helper Utility](https://dev.iopsys.eu/feed/iopsys/-/blob/devel/bbfdm/bbfdm.mk) * [JSON Plugin Validator](https://dev.iopsys.eu/feed/iopsys/-/blob/devel/bbfdm/tools/validate_plugins.py) -## Additional datamodel objects +## Additional Data Model Objects -This repository has bare minimal TR181 datamodel integrated, each service has their own datamodel additions, which they expose using plugins and micro-services. -List of IOWRT provided service datamodel set available in [tools_input.json](./tools/tools_input.json) +This repository has a bare minimum TR181 data model integrated. Each service has its own data model additions, which they expose using plugins and microservices. +A list of IOWRT-provided service data model sets is available in [tools_input.json](./tools/tools_input.json). ## Dependencies ### Build-Time Dependencies -To successfully build bbfdmd, following libraries are needed: +To successfully build `bbfdmd`, the following libraries are required: | Dependency | Link | License | | ------------ | ------------------------------------------- | -------- | @@ -83,21 +84,19 @@ To successfully build bbfdmd, following libraries are needed: | libjson-c | https://s3.amazonaws.com/json-c_releases | MIT | | libbbfdm-api | https://dev.iopsys.eu/bbf/bbfdm.git | BSD-3 | | libbbfdm-ubus | https://dev.iopsys.eu/bbf/bbfdm.git | BSD-3 | -| libbbfdm | https://dev.iopsys.eu/bbf/bbfdm.git | BSD-3 | - ### Run-Time Dependencies -In order to run the `bbfdmd`, following dependencies are needed to be running/available before `bbfdmd`. - -| Dependency | Link | License | -| ------------ | ---------------------------------------- | -------- | -| ubusd | https://git.openwrt.org/project/ubus.git | LGPL 2.1 | -| libbbfdm-api | https://dev.iopsys.eu/bbf/bbfdm.git | BSD-3 | -| libbbfdm-ubus | https://dev.iopsys.eu/bbf/bbfdm.git | BSD-3 | -| libbbfdm | https://dev.iopsys.eu/bbf/bbfdm.git | BSD-3 | - -In order to run the `dm-service`, following dependencies are needed to be running/available before `dm-service`. +To run `bbfdmd`, the following dependencies are required: + +| Dependency | Link | License | +| ------------ | ---------------------------------------- | -------- | +| ubusd | https://git.openwrt.org/project/ubus.git | LGPL 2.1 | +| libubox | https://git.openwrt.org/project/libubox.git | BSD | +| libjson-c | https://s3.amazonaws.com/json-c_releases | MIT | +| libbbfdm-api/version-2 | https://dev.iopsys.eu/bbf/bbfdm.git | BSD-3 | + +To run `dm-service`, the following dependencies are required: | Dependency | Link | License | | ------------ | ---------------------------------------- | -------- | diff --git a/docs/api/ubus/bbfdm.json b/docs/api/ubus/bbfdm.json index c01498e1..23600657 100644 --- a/docs/api/ubus/bbfdm.json +++ b/docs/api/ubus/bbfdm.json @@ -68,12 +68,6 @@ "Device.WiFi." ] }, - "instance_t": { - "description": "Multi object instances", - "type": "string", - "minLength": 6, - "maxLength": 256 - }, "proto_t": { "type": "string", "default": "both", @@ -104,22 +98,6 @@ "minimum": 7000, "maximum": 9050 }, - "trans_type_t": { - "type": "string", - "enum": [ - "start", - "commit", - "abort", - "status" - ] - }, - "srv_type_t": { - "type": "string", - "enum": [ - "register", - "list" - ] - }, "format_t": { "type": "string", "default": "pretty", @@ -150,31 +128,10 @@ "path": { "$ref": "#/definitions/query_path_t" }, - "paths": { - "type": "array", - "uniqueItems": true, - "items": [ - { - "$ref": "#/definitions/query_path_t" - } - ] - }, "first_level": { "type": "boolean", "description": "gets only first level objects if true" }, - "commands": { - "type": "boolean", - "description": "includes commands in the list if true" - }, - "events": { - "type": "boolean", - "description": "includes events in the list if true" - }, - "params": { - "type": "boolean", - "description": "includes objs/params in the list if true" - }, "optional": { "type": "object", "properties": { @@ -278,19 +235,6 @@ "path": { "$ref": "#/definitions/query_path_t" }, - "paths": { - "type": "array", - "uniqueItems": true, - "items": [ - { - "$ref": "#/definitions/query_path_t" - } - ] - }, - "maxdepth": { - "type": "integer", - "description": "Integer to decide the depth of data model to be parsed" - }, "optional": { "type": "object", "properties": { @@ -358,10 +302,6 @@ "path": { "$ref": "#/definitions/query_path_t" }, - "first_level": { - "type": "boolean", - "description": "gets only first level objects if true" - }, "optional": { "type": "object", "properties": { @@ -625,10 +565,10 @@ "input": { "type": "object", "required": [ - "command" + "path" ], "properties": { - "command": { + "path": { "$ref": "#/definitions/operate_path_t" }, "command_key": { @@ -645,9 +585,6 @@ "optional": { "type": "object", "properties": { - "format": { - "$ref": "#/definitions/format_t" - }, "proto": { "$ref": "#/definitions/proto_t" } @@ -709,8 +646,8 @@ } } }, - "service": { - "title": "show the list of micro-service registred in the core Data Model", + "services": { + "title": "show the list of micro-service registred in the Data Model", "type": "object", "required": [ "output" @@ -724,13 +661,21 @@ "type": "string", "Description": "Name of the micro-service ubus object" }, - "parent_dm": { - "type": "string", - "Description": "Object path where the micro-service object will be added" - }, - "object": { - "type": "string", - "Description": "Name of the micro-service object" + "objects": { + "type": "object", + "properties": { + "parent_dm": { + "type": "string", + "Description": "Object path where the micro-service object will be added" + }, + "object": { + "type": "string", + "Description": "Name of object will be added" + }, + "proto": { + "$ref": "#/definitions/proto_t" + } + } }, "proto": { "$ref": "#/definitions/proto_t" diff --git a/docs/api/ubus/bbfdm.md b/docs/api/ubus/bbfdm.md index e8754af4..dfbbcb8f 100644 --- a/docs/api/ubus/bbfdm.md +++ b/docs/api/ubus/bbfdm.md @@ -10,17 +10,16 @@ https://dev.iopsys.eu/bbf/bbfdm/-/blob/devel/docs/api/ubus/bbfdm.md # bbf -| List of Methods | -| ----------------------------- | -| [add](#add) | Method | bbf (this schema) | -| [del](#del) | Method | bbf (this schema) | -| [get](#get) | Method | bbf (this schema) | -| [instances](#instances) | Method | bbf (this schema) | -| [notify_event](#notify_event) | Method | bbf (this schema) | -| [operate](#operate) | Method | bbf (this schema) | -| [schema](#schema) | Method | bbf (this schema) | -| [service](#service) | Method | bbf (this schema) | -| [set](#set) | Method | bbf (this schema) | +| List of Methods | +| ----------------------- | +| [add](#add) | Method | bbf (this schema) | +| [del](#del) | Method | bbf (this schema) | +| [get](#get) | Method | bbf (this schema) | +| [instances](#instances) | Method | bbf (this schema) | +| [operate](#operate) | Method | bbf (this schema) | +| [schema](#schema) | Method | bbf (this schema) | +| [services](#services) | Method | bbf (this schema) | +| [set](#set) | Method | bbf (this schema) | ## add @@ -109,7 +108,7 @@ Device.WiFi. ### Ubus CLI Example ``` -ubus call bbf add {"path":"eu commodo Ut ut ","obj_path":{}} +ubus call bbf add {"path":"pariatur","obj_path":{}} ``` ### JSONRPC Example @@ -119,7 +118,7 @@ ubus call bbf add {"path":"eu commodo Ut ut ","obj_path":{}} "jsonrpc": "2.0", "id": 0, "method": "call", - "params": ["", "bbf", "add", { "path": "eu commodo Ut ut ", "obj_path": {} }] + "params": ["", "bbf", "add", { "path": "pariatur", "obj_path": {} }] } ``` @@ -186,10 +185,10 @@ All items must be of the type: Unknown type ``. { "results": [ { - "path": "eused exercitation", - "data": "pariatur nostrud in aute Excepteur", - "fault": 7415, - "fault_msg": "dolor magna" + "path": "enim ut voluptate eu ", + "data": "Ut in exercitation officia Excepteur", + "fault": 7966, + "fault_msg": "Ut" } ] } @@ -293,7 +292,7 @@ All items must be of the type: Unknown type ``. ### Ubus CLI Example ``` -ubus call bbf del {"path":"fugiat adipisicing","paths":["do laborum occaecat et"]} +ubus call bbf del {"path":"qui nisi id","paths":["adipis"]} ``` ### JSONRPC Example @@ -303,7 +302,7 @@ ubus call bbf del {"path":"fugiat adipisicing","paths":["do laborum occaecat et" "jsonrpc": "2.0", "id": 0, "method": "call", - "params": ["", "bbf", "del", { "path": "fugiat adipisicing", "paths": ["do laborum occaecat et"] }] + "params": ["", "bbf", "del", { "path": "qui nisi id", "paths": ["adipis"] }] } ``` @@ -367,7 +366,7 @@ All items must be of the type: Unknown type ``. ### Output Example ```json -{ "results": [{ "path": "occaecat sit elit i", "data": "non", "fault": 7119, "fault_msg": "elit sunt" }] } +{ "results": [{ "path": "sint elit", "data": "cupidatat do sit ", "fault": 8574, "fault_msg": "dolore et Duis" }] } ``` ## get @@ -400,25 +399,10 @@ Query the datamodel object `object` with following properties: -| Property | Type | Required | -| ---------- | ------- | ------------ | -| `maxdepth` | integer | Optional | -| `optional` | object | Optional | -| `path` | string | **Required** | -| `paths` | array | Optional | - -#### maxdepth - -Integer to decide the depth of data model to be parsed - -`maxdepth` - -- is optional -- type: `integer` - -##### maxdepth Type - -`integer` +| Property | Type | Required | +| ---------- | ------ | ------------ | +| `optional` | object | Optional | +| `path` | string | **Required** | #### optional @@ -517,36 +501,10 @@ Device.WiFi.SSID.*.BSSID Device.WiFi. ``` -#### paths - -`paths` - -- is optional -- type: `array` - -##### paths Type - -Array type: `array` - -All items must be of the type: Unknown type ``. - -```json -{ - "type": "array", - "uniqueItems": true, - "items": [ - { - "$ref": "#/definitions/query_path_t" - } - ], - "simpletype": "`array`" -} -``` - ### Ubus CLI Example ``` -ubus call bbf get {"path":"occaecat aliqua mollit","paths":["occaecat Duis Lorem velit aliq"],"maxdepth":-48387650,"optional":{"format":"raw","proto":"usp"}} +ubus call bbf get {"path":"magna consequat ut","optional":{"format":"pretty","proto":"both"}} ``` ### JSONRPC Example @@ -560,12 +518,7 @@ ubus call bbf get {"path":"occaecat aliqua mollit","paths":["occaecat Duis Lorem "", "bbf", "get", - { - "path": "occaecat aliqua mollit", - "paths": ["occaecat Duis Lorem velit aliq"], - "maxdepth": -48387650, - "optional": { "format": "raw", "proto": "usp" } - } + { "path": "magna consequat ut", "optional": { "format": "pretty", "proto": "both" } } ] } ``` @@ -633,7 +586,17 @@ All items must be of the type: Unknown type ``. ### Output Example ```json -{ "results": [{ "path": "dolore dolor", "data": "in", "type": "xsd:int", "fault": 7367, "fault_msg": "laborum nis" }] } +{ + "results": [ + { + "path": "id sunt Duis", + "data": "id", + "type": "xsd:command", + "fault": 8916, + "fault_msg": "dolor amet irure sed nulla" + } + ] +} ``` ## instances @@ -666,24 +629,10 @@ Get the instances of multi object `object` with following properties: -| Property | Type | Required | -| ------------- | ------- | ------------ | -| `first_level` | boolean | Optional | -| `optional` | object | Optional | -| `path` | string | **Required** | - -#### first_level - -gets only first level objects if true - -`first_level` - -- is optional -- type: `boolean` - -##### first_level Type - -`boolean` +| Property | Type | Required | +| ---------- | ------ | ------------ | +| `optional` | object | Optional | +| `path` | string | **Required** | #### optional @@ -763,7 +712,7 @@ Device.WiFi. ### Ubus CLI Example ``` -ubus call bbf instances {"path":"commodo aliqu","first_level":true,"optional":{"proto":"cwmp"}} +ubus call bbf instances {"path":"dolore n","optional":{"proto":"usp"}} ``` ### JSONRPC Example @@ -773,12 +722,7 @@ ubus call bbf instances {"path":"commodo aliqu","first_level":true,"optional":{" "jsonrpc": "2.0", "id": 0, "method": "call", - "params": [ - "", - "bbf", - "instances", - { "path": "commodo aliqu", "first_level": true, "optional": { "proto": "cwmp" } } - ] + "params": ["", "bbf", "instances", { "path": "dolore n", "optional": { "proto": "usp" } }] } ``` @@ -839,256 +783,7 @@ All items must be of the type: Unknown type ``. ### Output Example ```json -{ "results": [{ "path": "ametest minim ut sit ex", "fault": 7415, "fault_msg": "nostrud" }] } -``` - -## notify_event - -### notify occurance of an event on ubus - -`notify_event` - -- type: `Method` - -### notify_event Type - -`object` with following properties: - -| Property | Type | Required | -| -------- | ------ | ------------ | -| `input` | object | **Required** | -| `output` | | Optional | - -#### input - -`input` - -- is **required** -- type: `object` - -##### input Type - -`object` with following properties: - -| Property | Type | Required | -| -------- | ------ | ------------ | -| `input` | array | Optional | -| `name` | string | **Required** | - -#### input - -`input` - -- is optional -- type: `array` - -##### input Type - -Array type: `array` - -#### name - -`name` - -- is **required** -- type: `string` - -##### name Type - -`string` - -### Ubus CLI Example - -``` -ubus call bbf notify_event {"name":"Duis dolor officia anim Ut","input":[]} -``` - -### JSONRPC Example - -```json -{ - "jsonrpc": "2.0", - "id": 0, - "method": "call", - "params": ["", "bbf", "notify_event", { "name": "Duis dolor officia anim Ut", "input": [] }] -} -``` - -#### output - -`output` - -- is optional -- type: complex - -##### output Type - -Unknown type ``. - -```json -{ - "definitions": { - "path_t": { - "description": "Complete object element path as per TR181", - "type": "string", - "minLength": 6, - "maxLength": 1024, - "examples": ["Device.", "Device.DeviceInfo.Manufacturer", "Device.WiFi.SSID.1.", "Device.WiFi."] - }, - "schema_path_t": { - "description": "Datamodel object schema path", - "type": "string", - "minLength": 6, - "maxLength": 1024, - "examples": ["Device.Bridging.Bridge.{i}.", "Device.DeviceInfo.Manufacturer", "Device.WiFi.SSID.{i}.SSID"] - }, - "boolean_t": { - "type": "string", - "enum": ["0", "1"] - }, - "datatype_t": { - "type": "string", - "enum": ["int", "unsignedInt", "long", "unsignedLong", "string", "boolean", "dateTime", "base64", "hexBinary"] - }, - "operate_path_t": { - "description": "Datamodel object schema path", - "type": "string", - "minLength": 6, - "maxLength": 1024, - "examples": ["Device.IP.Diagnostics.IPPing()", "Device.DHCPv4.Client.{i}.Renew()", "Device.FactoryReset()"] - }, - "query_path_t": { - "description": "DM object path with search queries", - "type": "string", - "minLength": 6, - "maxLength": 1024, - "examples": [ - "Device.", - "Device.DeviceInfo.Manufacturer", - "Device.WiFi.SSID.1.BSSID", - "Device.WiFi.SSID.*.BSSID", - "Device.WiFi." - ] - }, - "instance_t": { - "description": "Multi object instances", - "type": "string", - "minLength": 6, - "maxLength": 256 - }, - "proto_t": { - "type": "string", - "default": "both", - "enum": ["usp", "cwmp", "both"] - }, - "type_t": { - "type": "string", - "enum": [ - "xsd:string", - "xsd:unsignedInt", - "xsd:int", - "xsd:unsignedLong", - "xsd:long", - "xsd:boolean", - "xsd:dateTime", - "xsd:hexBinary", - "xsd:object", - "xsd:command", - "xsd:event" - ] - }, - "fault_t": { - "type": "integer", - "minimum": 7000, - "maximum": 9050 - }, - "trans_type_t": { - "type": "string", - "enum": ["start", "commit", "abort", "status"] - }, - "srv_type_t": { - "type": "string", - "enum": ["register", "list"] - }, - "format_t": { - "type": "string", - "default": "pretty", - "enum": ["raw", "pretty"] - } - }, - "out": "{\"definitions\":{\"path_t\":{\"description\":\"Complete object element path as per TR181\",\"type\":\"string\",\"minLength\":6,\"maxLength\":1024,\"examples\":[\"Device.\",\"Device.DeviceInfo.Manufacturer\",\"Device.WiFi.SSID.1.\",\"Device.WiFi.\"]},\"schema_path_t\":{\"description\":\"Datamodel object schema path\",\"type\":\"string\",\"minLength\":6,\"maxLength\":1024,\"examples\":[\"Device.Bridging.Bridge.{i}.\",\"Device.DeviceInfo.Manufacturer\",\"Device.WiFi.SSID.{i}.SSID\"]},\"boolean_t\":{\"type\":\"string\",\"enum\":[\"0\",\"1\"]},\"datatype_t\":{\"type\":\"string\",\"enum\":[\"int\",\"unsignedInt\",\"long\",\"unsignedLong\",\"string\",\"boolean\",\"dateTime\",\"base64\",\"hexBinary\"]},\"operate_path_t\":{\"description\":\"Datamodel object schema path\",\"type\":\"string\",\"minLength\":6,\"maxLength\":1024,\"examples\":[\"Device.IP.Diagnostics.IPPing()\",\"Device.DHCPv4.Client.{i}.Renew()\",\"Device.FactoryReset()\"]},\"query_path_t\":{\"description\":\"DM object path with search queries\",\"type\":\"string\",\"minLength\":6,\"maxLength\":1024,\"examples\":[\"Device.\",\"Device.DeviceInfo.Manufacturer\",\"Device.WiFi.SSID.1.BSSID\",\"Device.WiFi.SSID.*.BSSID\",\"Device.WiFi.\"]},\"instance_t\":{\"description\":\"Multi object instances\",\"type\":\"string\",\"minLength\":6,\"maxLength\":256},\"proto_t\":{\"type\":\"string\",\"default\":\"both\",\"enum\":[\"usp\",\"cwmp\",\"both\"]},\"type_t\":{\"type\":\"string\",\"enum\":[\"xsd:string\",\"xsd:unsignedInt\",\"xsd:int\",\"xsd:unsignedLong\",\"xsd:long\",\"xsd:boolean\",\"xsd:dateTime\",\"xsd:hexBinary\",\"xsd:object\",\"xsd:command\",\"xsd:event\"]},\"fault_t\":{\"type\":\"integer\",\"minimum\":7000,\"maximum\":9050},\"trans_type_t\":{\"type\":\"string\",\"enum\":[\"start\",\"commit\",\"abort\",\"status\"]},\"srv_type_t\":{\"type\":\"string\",\"enum\":[\"register\",\"list\"]},\"format_t\":{\"type\":\"string\",\"default\":\"pretty\",\"enum\":[\"raw\",\"pretty\"]}}}", - "simpletype": "complex" -} -``` - -### Output Example - -```json -{ - "definitions": { - "path_t": { - "description": "Complete object element path as per TR181", - "type": "string", - "minLength": 6, - "maxLength": 1024, - "examples": ["Device.", "Device.DeviceInfo.Manufacturer", "Device.WiFi.SSID.1.", "Device.WiFi."] - }, - "schema_path_t": { - "description": "Datamodel object schema path", - "type": "string", - "minLength": 6, - "maxLength": 1024, - "examples": ["Device.Bridging.Bridge.{i}.", "Device.DeviceInfo.Manufacturer", "Device.WiFi.SSID.{i}.SSID"] - }, - "boolean_t": { "type": "string", "enum": ["0", "1"] }, - "datatype_t": { - "type": "string", - "enum": ["int", "unsignedInt", "long", "unsignedLong", "string", "boolean", "dateTime", "base64", "hexBinary"] - }, - "operate_path_t": { - "description": "Datamodel object schema path", - "type": "string", - "minLength": 6, - "maxLength": 1024, - "examples": ["Device.IP.Diagnostics.IPPing()", "Device.DHCPv4.Client.{i}.Renew()", "Device.FactoryReset()"] - }, - "query_path_t": { - "description": "DM object path with search queries", - "type": "string", - "minLength": 6, - "maxLength": 1024, - "examples": [ - "Device.", - "Device.DeviceInfo.Manufacturer", - "Device.WiFi.SSID.1.BSSID", - "Device.WiFi.SSID.*.BSSID", - "Device.WiFi." - ] - }, - "instance_t": { "description": "Multi object instances", "type": "string", "minLength": 6, "maxLength": 256 }, - "proto_t": { "type": "string", "default": "both", "enum": ["usp", "cwmp", "both"] }, - "type_t": { - "type": "string", - "enum": [ - "xsd:string", - "xsd:unsignedInt", - "xsd:int", - "xsd:unsignedLong", - "xsd:long", - "xsd:boolean", - "xsd:dateTime", - "xsd:hexBinary", - "xsd:object", - "xsd:command", - "xsd:event" - ] - }, - "fault_t": { "type": "integer", "minimum": 7000, "maximum": 9050 }, - "trans_type_t": { "type": "string", "enum": ["start", "commit", "abort", "status"] }, - "srv_type_t": { "type": "string", "enum": ["register", "list"] }, - "format_t": { "type": "string", "default": "pretty", "enum": ["raw", "pretty"] } - } -} +{ "results": [{ "path": "veniam amet", "fault": 7810, "fault_msg": "quis" }] } ``` ## operate @@ -1123,40 +818,10 @@ Operate on object element provided in path | Property | Type | Required | | ------------- | ------ | ------------ | -| `command` | string | **Required** | | `command_key` | string | Optional | | `input` | object | Optional | | `optional` | object | Optional | - -#### command - -Datamodel object schema path - -`command` - -- is **required** -- type: reference - -##### command Type - -`string` - -- minimum length: 6 characters -- maximum length: 1024 characters - -##### command Examples - -```json -Device.IP.Diagnostics.IPPing() -``` - -```json -Device.DHCPv4.Client.{i}.Renew() -``` - -```json -Device.FactoryReset() -``` +| `path` | string | **Required** | #### command_key @@ -1203,31 +868,9 @@ Input arguments for the operate command as defined in TR-181-2.13 `object` with following properties: -| Property | Type | Required | Default | -| -------- | ------ | -------- | ---------- | -| `format` | string | Optional | `"pretty"` | -| `proto` | string | Optional | `"both"` | - -#### format - -`format` - -- is optional -- type: reference -- default: `"pretty"` - -##### format Type - -`string` - -The value of this property **must** be equal to one of the [known values below](#operate-known-values). - -##### format Known Values - -| Value | -| ------ | -| raw | -| pretty | +| Property | Type | Required | Default | +| -------- | ------ | -------- | -------- | +| `proto` | string | Optional | `"both"` | #### proto @@ -1251,10 +894,40 @@ The value of this property **must** be equal to one of the [known values below]( | cwmp | | both | +#### path + +Datamodel object schema path + +`path` + +- is **required** +- type: reference + +##### path Type + +`string` + +- minimum length: 6 characters +- maximum length: 1024 characters + +##### path Examples + +```json +Device.IP.Diagnostics.IPPing() +``` + +```json +Device.DHCPv4.Client.{i}.Renew() +``` + +```json +Device.FactoryReset() +``` + ### Ubus CLI Example ``` -ubus call bbf operate {"command":"dolore anim dolor","command_key":"in eiusmod in culpa non","input":{},"optional":{"format":"pretty","proto":"both"}} +ubus call bbf operate {"path":"velit nostrud ullamco","command_key":"ullamco officia nulla pariatur","input":{},"optional":{"proto":"both"}} ``` ### JSONRPC Example @@ -1269,10 +942,10 @@ ubus call bbf operate {"command":"dolore anim dolor","command_key":"in eiusmod i "bbf", "operate", { - "command": "dolore anim dolor", - "command_key": "in eiusmod in culpa non", + "path": "velit nostrud ullamco", + "command_key": "ullamco officia nulla pariatur", "input": {}, - "optional": { "format": "pretty", "proto": "both" } + "optional": { "proto": "both" } } ] } @@ -1360,11 +1033,11 @@ All items must be of the type: Unknown type ``. { "results": [ { - "path": "eteu veniam fugiat al", - "data": "1", - "fault": 8377, - "fault_msg": "cillum magna", - "output": [{ "path": "irurein", "data": "0", "type": "xsd:boolean" }] + "path": "sitveniam pa", + "data": "0", + "fault": 8302, + "fault_msg": "eiusmod laborum", + "output": [{ "path": "dolore pariatur qui", "data": "0", "type": "xsd:dateTime" }] } ] } @@ -1402,39 +1075,9 @@ Schema will have all the nodes/objects supported by libbbf | Property | Type | Required | | ------------- | ------- | -------- | -| `commands` | boolean | Optional | -| `events` | boolean | Optional | | `first_level` | boolean | Optional | | `optional` | object | Optional | -| `params` | boolean | Optional | | `path` | string | Optional | -| `paths` | array | Optional | - -#### commands - -includes commands in the list if true - -`commands` - -- is optional -- type: `boolean` - -##### commands Type - -`boolean` - -#### events - -includes events in the list if true - -`events` - -- is optional -- type: `boolean` - -##### events Type - -`boolean` #### first_level @@ -1486,19 +1129,6 @@ The value of this property **must** be equal to one of the [known values below]( | cwmp | | both | -#### params - -includes objs/params in the list if true - -`params` - -- is optional -- type: `boolean` - -##### params Type - -`boolean` - #### path DM object path with search queries @@ -1537,36 +1167,10 @@ Device.WiFi.SSID.*.BSSID Device.WiFi. ``` -#### paths - -`paths` - -- is optional -- type: `array` - -##### paths Type - -Array type: `array` - -All items must be of the type: Unknown type ``. - -```json -{ - "type": "array", - "uniqueItems": true, - "items": [ - { - "$ref": "#/definitions/query_path_t" - } - ], - "simpletype": "`array`" -} -``` - ### Ubus CLI Example ``` -ubus call bbf schema {"path":"ipsum aliqua","paths":["enim quis laborum"],"first_level":false,"commands":true,"events":false,"params":false,"optional":{"proto":"usp"}} +ubus call bbf schema {"path":"idnisi Lorem","first_level":true,"optional":{"proto":"both"}} ``` ### JSONRPC Example @@ -1580,15 +1184,7 @@ ubus call bbf schema {"path":"ipsum aliqua","paths":["enim quis laborum"],"first "", "bbf", "schema", - { - "path": "ipsum aliqua", - "paths": ["enim quis laborum"], - "first_level": false, - "commands": true, - "events": false, - "params": false, - "optional": { "proto": "usp" } - } + { "path": "idnisi Lorem", "first_level": true, "optional": { "proto": "both" } } ] } ``` @@ -1697,27 +1293,27 @@ All items must be of the type: Unknown type ``. { "results": [ { - "path": "et sunt id", + "path": "deserunt sed", "data": "0", - "type": "xsd:command", - "fault": 8958, - "fault_msg": "vel", - "input": [{ "path": "nisi elit amet", "data": "0", "type": "xsd:object" }], - "output": [{ "path": "anim pariatur ipsum et", "data": "1", "type": "xsd:unsignedLong" }] + "type": "xsd:event", + "fault": 7839, + "fault_msg": "velit sed", + "input": [{ "path": "ullamco magna aliquip", "data": "0", "type": "xsd:dateTime" }], + "output": [{ "path": "aliqua", "data": "0", "type": "xsd:long" }] } ] } ``` -## service +## services -### show the list of micro-service registred in the core Data Model +### show the list of micro-service registred in the Data Model -`service` +`services` - type: `Method` -### service Type +### services Type `object` with following properties: @@ -1757,8 +1353,7 @@ Unknown type ``. | Property | Type | Required | Default | | ---------------- | ------- | -------- | -------- | | `name` | string | Optional | | -| `object` | string | Optional | | -| `parent_dm` | string | Optional | | +| `objects` | object | Optional | | | `proto` | string | Optional | `"both"` | | `unified_daemon` | boolean | Optional | | @@ -1773,6 +1368,23 @@ Unknown type ``. `string` +#### objects + +`objects` + +- is optional +- type: `object` + +##### objects Type + +`object` with following properties: + +| Property | Type | Required | Default | +| ----------- | ------ | -------- | -------- | +| `object` | string | Optional | | +| `parent_dm` | string | Optional | | +| `proto` | string | Optional | `"both"` | + #### object `object` @@ -1807,7 +1419,29 @@ Unknown type ``. `string` -The value of this property **must** be equal to one of the [known values below](#service-known-values). +The value of this property **must** be equal to one of the [known values below](#services-known-values). + +##### proto Known Values + +| Value | +| ----- | +| usp | +| cwmp | +| both | + +#### proto + +`proto` + +- is optional +- type: reference +- default: `"both"` + +##### proto Type + +`string` + +The value of this property **must** be equal to one of the [known values below](#services-known-values). ##### proto Known Values @@ -1832,9 +1466,8 @@ The value of this property **must** be equal to one of the [known values below]( ```json { - "name": "incididunt cillum Excepteur ipsum laborum", - "parent_dm": "consectetur Excepteur eiusmod aliqua minim", - "object": "nostrud incididunt", + "name": "reprehenderit proident nisi", + "objects": { "parent_dm": "adipisicing culpa in", "object": "elit", "proto": "both" }, "proto": "usp", "unified_daemon": false } @@ -2039,7 +1672,7 @@ value of the object element provided in path, path should contains valid writabl ### Ubus CLI Example ``` -ubus call bbf set {"path":"aliqua aliquip","value":"aliqua","datatype":"int","obj_path":{}} +ubus call bbf set {"path":"consectetur proident Ut consequat tempor","value":"cillum quis sed aliquip","datatype":"boolean","obj_path":{}} ``` ### JSONRPC Example @@ -2049,7 +1682,17 @@ ubus call bbf set {"path":"aliqua aliquip","value":"aliqua","datatype":"int","ob "jsonrpc": "2.0", "id": 0, "method": "call", - "params": ["", "bbf", "set", { "path": "aliqua aliquip", "value": "aliqua", "datatype": "int", "obj_path": {} }] + "params": [ + "", + "bbf", + "set", + { + "path": "consectetur proident Ut consequat tempor", + "value": "cillum quis sed aliquip", + "datatype": "boolean", + "obj_path": {} + } + ] } ``` @@ -2113,5 +1756,5 @@ All items must be of the type: Unknown type ``. ### Output Example ```json -{ "results": [{ "path": "in est veniam incididunt", "data": "1", "fault": 7720, "fault_msg": "anim" }] } +{ "results": [{ "path": "quis u", "data": "1", "fault": 7028, "fault_msg": "qui pariatur ipsum nisi" }] } ``` diff --git a/docs/api/ubus/bbfdm_micro_service.json b/docs/api/ubus/bbfdm_micro_service.json index 6eaeb9b2..e02d13fb 100644 --- a/docs/api/ubus/bbfdm_micro_service.json +++ b/docs/api/ubus/bbfdm_micro_service.json @@ -68,12 +68,6 @@ "Device.WiFi." ] }, - "instance_t": { - "description": "Multi object instances", - "type": "string", - "minLength": 6, - "maxLength": 256 - }, "proto_t": { "type": "string", "default": "both", @@ -104,22 +98,6 @@ "minimum": 7000, "maximum": 9050 }, - "trans_type_t": { - "type": "string", - "enum": [ - "start", - "commit", - "abort", - "status" - ] - }, - "srv_type_t": { - "type": "string", - "enum": [ - "register", - "list" - ] - }, "format_t": { "type": "string", "default": "pretty", @@ -150,31 +128,10 @@ "path": { "$ref": "#/definitions/query_path_t" }, - "paths": { - "type": "array", - "uniqueItems": true, - "items": [ - { - "$ref": "#/definitions/query_path_t" - } - ] - }, "first_level": { "type": "boolean", "description": "gets only first level objects if true" }, - "commands": { - "type": "boolean", - "description": "includes commands in the list if true" - }, - "events": { - "type": "boolean", - "description": "includes events in the list if true" - }, - "params": { - "type": "boolean", - "description": "includes objs/params in the list if true" - }, "optional": { "type": "object", "properties": { @@ -278,19 +235,6 @@ "path": { "$ref": "#/definitions/query_path_t" }, - "paths": { - "type": "array", - "uniqueItems": true, - "items": [ - { - "$ref": "#/definitions/query_path_t" - } - ] - }, - "maxdepth": { - "type": "integer", - "description": "Integer to decide the depth of data model to be parsed" - }, "optional": { "type": "object", "properties": { @@ -358,10 +302,6 @@ "path": { "$ref": "#/definitions/query_path_t" }, - "first_level": { - "type": "boolean", - "description": "gets only first level objects if true" - }, "optional": { "type": "object", "properties": { @@ -625,10 +565,10 @@ "input": { "type": "object", "required": [ - "command" + "path" ], "properties": { - "command": { + "path": { "$ref": "#/definitions/operate_path_t" }, "command_key": { diff --git a/docs/api/ubus/bbfdm_micro_service.md b/docs/api/ubus/bbfdm_micro_service.md index 579e96da..efe024d5 100644 --- a/docs/api/ubus/bbfdm_micro_service.md +++ b/docs/api/ubus/bbfdm_micro_service.md @@ -107,7 +107,7 @@ Device.WiFi. ### Ubus CLI Example ``` -ubus call bbf add {"path":"eu qui","obj_path":{}} +ubus call bbf add {"path":"eucommodo voluptate cillum","obj_path":{}} ``` ### JSONRPC Example @@ -117,7 +117,7 @@ ubus call bbf add {"path":"eu qui","obj_path":{}} "jsonrpc": "2.0", "id": 0, "method": "call", - "params": ["", "bbf", "add", { "path": "eu qui", "obj_path": {} }] + "params": ["", "bbf", "add", { "path": "eucommodo voluptate cillum", "obj_path": {} }] } ``` @@ -183,7 +183,12 @@ All items must be of the type: Unknown type ``. ```json { "results": [ - { "path": "magna enim", "data": "in aliquip id eu deserunt", "fault": 8757, "fault_msg": "quis id ut in" } + { + "path": "eiusmod consequ", + "data": "adipisicing incidid", + "fault": 8484, + "fault_msg": "in labore nostrud voluptate est" + } ] } ``` @@ -286,7 +291,7 @@ All items must be of the type: Unknown type ``. ### Ubus CLI Example ``` -ubus call bbf del {"path":"incididunt tempor","paths":["dolore aliqua labore labori"]} +ubus call bbf del {"path":"eiusmod c","paths":["utamet incididunt fugiat in labore"]} ``` ### JSONRPC Example @@ -296,7 +301,7 @@ ubus call bbf del {"path":"incididunt tempor","paths":["dolore aliqua labore lab "jsonrpc": "2.0", "id": 0, "method": "call", - "params": ["", "bbf", "del", { "path": "incididunt tempor", "paths": ["dolore aliqua labore labori"] }] + "params": ["", "bbf", "del", { "path": "eiusmod c", "paths": ["utamet incididunt fugiat in labore"] }] } ``` @@ -362,7 +367,12 @@ All items must be of the type: Unknown type ``. ```json { "results": [ - { "path": "aliqua id deserunt", "data": "reprehenderit eu sed esse", "fault": 8791, "fault_msg": "occaecat" } + { + "path": "eiusmod ipsum", + "data": "Lorem sunt laboris occaecat dolor", + "fault": 7023, + "fault_msg": "aute proident" + } ] } ``` @@ -397,25 +407,10 @@ Query the datamodel object `object` with following properties: -| Property | Type | Required | -| ---------- | ------- | ------------ | -| `maxdepth` | integer | Optional | -| `optional` | object | Optional | -| `path` | string | **Required** | -| `paths` | array | Optional | - -#### maxdepth - -Integer to decide the depth of data model to be parsed - -`maxdepth` - -- is optional -- type: `integer` - -##### maxdepth Type - -`integer` +| Property | Type | Required | +| ---------- | ------ | ------------ | +| `optional` | object | Optional | +| `path` | string | **Required** | #### optional @@ -514,36 +509,10 @@ Device.WiFi.SSID.*.BSSID Device.WiFi. ``` -#### paths - -`paths` - -- is optional -- type: `array` - -##### paths Type - -Array type: `array` - -All items must be of the type: Unknown type ``. - -```json -{ - "type": "array", - "uniqueItems": true, - "items": [ - { - "$ref": "#/definitions/query_path_t" - } - ], - "simpletype": "`array`" -} -``` - ### Ubus CLI Example ``` -ubus call bbf get {"path":"auteaute","paths":["culpa amet elit irure"],"maxdepth":-44630385,"optional":{"format":"raw","proto":"cwmp"}} +ubus call bbf get {"path":"Lorem c","optional":{"format":"raw","proto":"both"}} ``` ### JSONRPC Example @@ -553,17 +522,7 @@ ubus call bbf get {"path":"auteaute","paths":["culpa amet elit irure"],"maxdepth "jsonrpc": "2.0", "id": 0, "method": "call", - "params": [ - "", - "bbf", - "get", - { - "path": "auteaute", - "paths": ["culpa amet elit irure"], - "maxdepth": -44630385, - "optional": { "format": "raw", "proto": "cwmp" } - } - ] + "params": ["", "bbf", "get", { "path": "Lorem c", "optional": { "format": "raw", "proto": "both" } }] } ``` @@ -633,11 +592,11 @@ All items must be of the type: Unknown type ``. { "results": [ { - "path": "dolore eu", - "data": "et sit exercitation cupid", - "type": "xsd:string", - "fault": 7957, - "fault_msg": "sit l" + "path": "eiusmod consectetu", + "data": "laborum non", + "type": "xsd:hexBinary", + "fault": 7671, + "fault_msg": "enim ea fugiat velit nulla" } ] } @@ -673,24 +632,10 @@ Get the instances of multi object `object` with following properties: -| Property | Type | Required | -| ------------- | ------- | ------------ | -| `first_level` | boolean | Optional | -| `optional` | object | Optional | -| `path` | string | **Required** | - -#### first_level - -gets only first level objects if true - -`first_level` - -- is optional -- type: `boolean` - -##### first_level Type - -`boolean` +| Property | Type | Required | +| ---------- | ------ | ------------ | +| `optional` | object | Optional | +| `path` | string | **Required** | #### optional @@ -770,7 +715,7 @@ Device.WiFi. ### Ubus CLI Example ``` -ubus call bbf instances {"path":"laborum magna Excepteur est","first_level":false,"optional":{"proto":"usp"}} +ubus call bbf instances {"path":"sint culpa laborum","optional":{"proto":"usp"}} ``` ### JSONRPC Example @@ -780,12 +725,7 @@ ubus call bbf instances {"path":"laborum magna Excepteur est","first_level":fals "jsonrpc": "2.0", "id": 0, "method": "call", - "params": [ - "", - "bbf", - "instances", - { "path": "laborum magna Excepteur est", "first_level": false, "optional": { "proto": "usp" } } - ] + "params": ["", "bbf", "instances", { "path": "sint culpa laborum", "optional": { "proto": "usp" } }] } ``` @@ -846,7 +786,7 @@ All items must be of the type: Unknown type ``. ### Output Example ```json -{ "results": [{ "path": "Duis dolor e", "fault": 8621, "fault_msg": "et nulla" }] } +{ "results": [{ "path": "labore Lorem in", "fault": 8069, "fault_msg": "adipisicing non anim cupidatat amet" }] } ``` ## operate @@ -881,40 +821,10 @@ Operate on object element provided in path | Property | Type | Required | | ------------- | ------ | ------------ | -| `command` | string | **Required** | | `command_key` | string | Optional | | `input` | object | Optional | | `optional` | object | Optional | - -#### command - -Datamodel object schema path - -`command` - -- is **required** -- type: reference - -##### command Type - -`string` - -- minimum length: 6 characters -- maximum length: 1024 characters - -##### command Examples - -```json -Device.IP.Diagnostics.IPPing() -``` - -```json -Device.DHCPv4.Client.{i}.Renew() -``` - -```json -Device.FactoryReset() -``` +| `path` | string | **Required** | #### command_key @@ -1009,10 +919,40 @@ The value of this property **must** be equal to one of the [known values below]( | cwmp | | both | +#### path + +Datamodel object schema path + +`path` + +- is **required** +- type: reference + +##### path Type + +`string` + +- minimum length: 6 characters +- maximum length: 1024 characters + +##### path Examples + +```json +Device.IP.Diagnostics.IPPing() +``` + +```json +Device.DHCPv4.Client.{i}.Renew() +``` + +```json +Device.FactoryReset() +``` + ### Ubus CLI Example ``` -ubus call bbf operate {"command":"in cupidatat minim reprehenderit","command_key":"cillum aliqua anim et veniam","input":{},"optional":{"format":"pretty","proto":"usp"}} +ubus call bbf operate {"path":"aliqua elit deserunt","command_key":"nostrud aute sed","input":{},"optional":{"format":"raw","proto":"cwmp"}} ``` ### JSONRPC Example @@ -1027,10 +967,10 @@ ubus call bbf operate {"command":"in cupidatat minim reprehenderit","command_key "bbf", "operate", { - "command": "in cupidatat minim reprehenderit", - "command_key": "cillum aliqua anim et veniam", + "path": "aliqua elit deserunt", + "command_key": "nostrud aute sed", "input": {}, - "optional": { "format": "pretty", "proto": "usp" } + "optional": { "format": "raw", "proto": "cwmp" } } ] } @@ -1118,11 +1058,11 @@ All items must be of the type: Unknown type ``. { "results": [ { - "path": "doDuis", - "data": "0", - "fault": 8434, - "fault_msg": "co", - "output": [{ "path": "anim vel", "data": "1", "type": "xsd:unsignedLong" }] + "path": "do cillum", + "data": "1", + "fault": 8145, + "fault_msg": "velit irure dolore qui proident", + "output": [{ "path": "labore", "data": "1", "type": "xsd:int" }] } ] } @@ -1160,39 +1100,9 @@ Schema will have all the nodes/objects supported by libbbf | Property | Type | Required | | ------------- | ------- | -------- | -| `commands` | boolean | Optional | -| `events` | boolean | Optional | | `first_level` | boolean | Optional | | `optional` | object | Optional | -| `params` | boolean | Optional | | `path` | string | Optional | -| `paths` | array | Optional | - -#### commands - -includes commands in the list if true - -`commands` - -- is optional -- type: `boolean` - -##### commands Type - -`boolean` - -#### events - -includes events in the list if true - -`events` - -- is optional -- type: `boolean` - -##### events Type - -`boolean` #### first_level @@ -1244,19 +1154,6 @@ The value of this property **must** be equal to one of the [known values below]( | cwmp | | both | -#### params - -includes objs/params in the list if true - -`params` - -- is optional -- type: `boolean` - -##### params Type - -`boolean` - #### path DM object path with search queries @@ -1295,36 +1192,10 @@ Device.WiFi.SSID.*.BSSID Device.WiFi. ``` -#### paths - -`paths` - -- is optional -- type: `array` - -##### paths Type - -Array type: `array` - -All items must be of the type: Unknown type ``. - -```json -{ - "type": "array", - "uniqueItems": true, - "items": [ - { - "$ref": "#/definitions/query_path_t" - } - ], - "simpletype": "`array`" -} -``` - ### Ubus CLI Example ``` -ubus call bbf schema {"path":"Excepteur dolor","paths":["adipisicing veniam"],"first_level":true,"commands":false,"events":true,"params":false,"optional":{"proto":"both"}} +ubus call bbf schema {"path":"eiusmod in nostrud Excepteur","first_level":false,"optional":{"proto":"usp"}} ``` ### JSONRPC Example @@ -1338,15 +1209,7 @@ ubus call bbf schema {"path":"Excepteur dolor","paths":["adipisicing veniam"],"f "", "bbf", "schema", - { - "path": "Excepteur dolor", - "paths": ["adipisicing veniam"], - "first_level": true, - "commands": false, - "events": true, - "params": false, - "optional": { "proto": "both" } - } + { "path": "eiusmod in nostrud Excepteur", "first_level": false, "optional": { "proto": "usp" } } ] } ``` @@ -1455,13 +1318,13 @@ All items must be of the type: Unknown type ``. { "results": [ { - "path": "ad dolore eiusmo", + "path": "id deserunt exer", "data": "1", - "type": "xsd:unsignedInt", - "fault": 8099, - "fault_msg": "amet laboris", - "input": [{ "path": "dolor cillum nulla", "data": "1", "type": "xsd:int" }], - "output": [{ "path": "ut eu i", "data": "0", "type": "xsd:object" }] + "type": "xsd:string", + "fault": 9040, + "fault_msg": "velit", + "input": [{ "path": "innostrud quis sit", "data": "0", "type": "xsd:string" }], + "output": [{ "path": "sint quis aliqua", "data": "0", "type": "xsd:unsignedLong" }] } ] } @@ -1666,7 +1529,7 @@ value of the object element provided in path, path should contains valid writabl ### Ubus CLI Example ``` -ubus call bbf set {"path":"sint nulla nisi reprehenderit dol","value":"aliqua sit aliquip","datatype":"long","obj_path":{}} +ubus call bbf set {"path":"aliquip consequat fugiat","value":"esse","datatype":"hexBinary","obj_path":{}} ``` ### JSONRPC Example @@ -1680,7 +1543,7 @@ ubus call bbf set {"path":"sint nulla nisi reprehenderit dol","value":"aliqua si "", "bbf", "set", - { "path": "sint nulla nisi reprehenderit dol", "value": "aliqua sit aliquip", "datatype": "long", "obj_path": {} } + { "path": "aliquip consequat fugiat", "value": "esse", "datatype": "hexBinary", "obj_path": {} } ] } ``` @@ -1745,5 +1608,5 @@ All items must be of the type: Unknown type ``. ### Output Example ```json -{ "results": [{ "path": "in esse et", "data": "1", "fault": 8550, "fault_msg": "incididunt in Ut nisi" }] } +{ "results": [{ "path": "auteconsequat in", "data": "0", "fault": 8847, "fault_msg": "irure esse Lorem" }] } ``` diff --git a/docs/guide/bbfdmd.md b/docs/guide/bbfdmd.md index 39495853..5e12553f 100644 --- a/docs/guide/bbfdmd.md +++ b/docs/guide/bbfdmd.md @@ -1,89 +1,143 @@ -# BBFDM Daemon (bbfdmd) +# BBFDM Daemon (`bbfdmd`) -`bbfdmd` daemon responsible for creating a datamodel layer between system resources and exposing TR181 data-model objects over ubus for higher layer application protocols like [TR-069/cwmp](https://cwmp-data-models.broadband-forum.org/) or [TR-369/USP](https://usp.technology/). +`bbfdmd` daemon creates a data model layer between system resources and exposes TR-181 data model objects over `ubus` for higher-layer application protocols such as [TR-069/CWMP](https://cwmp-data-models.broadband-forum.org/) or [TR-369/USP](https://usp.technology/). -> Note 1: The command outputs shown in this document are examples only, actual output may differ based on device and configuration. +> **Note:** The command outputs shown in this document are examples. The actual output may vary depending on the device and configuration. + +--- ## Concepts and Workflow -`bbfdmd` daemon gets started by `/etc/init.d/bbfdmd` service, bbfdmd init script reads the input from `bbfdm` uci file and then it starts using the APIs provided by `libbbfdm-ubus` and `libbbfdm-api`. +`bbfdmd` daemon collects data models from various microservices and exposes them over `ubus`. It does not handle the data model internally or validate its existence. -`bbfdmd` daemon use `libbbfdm-api` library to traverse the core datamodel tree added by static library `libbbfdm` or other plugins defined in `/usr/share/bbfdm/plugins`. +### Initialization -`bbfdmd` daemon use `libbbfdm-ubus` library to expose datamodel over ubus. +1. The `bbfdmd` daemon is started by the `/etc/init.d/bbfdmd` service. +2. During startup, it registers all available microservices listed under `/etc/bbfdm/service/` by parsing each JSON file to extract information such as: + - `service_name` + - Data model paths exposed by the service + - Protocol visibility (CWMP or USP) +3. After processing the JSON files, it registers the supported `bbfdm` ubus methods. -When a ubus method is called it first fills `bbfdm_data_t` structure with the necessary information, then register the micro-services information defined for each JSON service file after that proceeds the `Get/Set/Operate/Add/Del` operation based on that information. +### Handling Ubus Calls -To load the datamodel definitions from a DotSO file, it looks for a 'tDynamicObj' symbol and use it to create the base entry object, for datamodel operations it rely on libbbfdm-api's `bbf_entry_method` which process the datamodel operation on input path and produces result in list/blob, which further gets responded over ubus. +When a `bbfdm` ubus object is called, the daemon determines the handling type based on the ubus method: -In short, it covers/supports all methods introduced in `TR-069` and `TR-369` by using the `bbf_entry_method` API from `libbbfdm-api` with the different methods and the existing data-model available with `libbbfdm`. +- **Asynchronous methods** (`get`, `schema`, `instances`, `operate`) + These methods are executed asynchronously to collect data model output from multiple microservices simultaneously. -> Note1: In general, bbfdmd does not reload the services after updating the configs, higher layer applications (i.e. icwmp, obuspa) usages `bbf.config` to apply the configs and reloads the services, please check `bbf.config` documentation for more details. +- **Synchronous methods** (`set`, `add`, `delete`) + These methods are executed synchronously because they only target a specific microservice. -> Note2: All RPC method's output is stored directly in a blob buffer, which can be used at the end by Ubus reply API to expose the data and reducing CPU usage of `bbfdmd` daemon. +### Microservice Identification -## Input and output Schema(s) +To identify which microservice to call, `bbfdm`: +- Extracts the requested path from the `"path"` input. +- Retrieves the protocol from `"optional.proto"` input. +- Matches the extracted path and protocol against the list of registered services. -`bbfdmd` basic configuration can be updated with uci, a guide and uci schema available in following links -- [bbfdm uci guide](../api/uci/bbfdm.md) -- [bbfdm uci schema](../api/uci/bbfdm.json) +--- -`bbfdmd` ubus guide and schema -- [bbfdm ubus guide](../api/ubus/bbfdm.md) -- [bbfdm ubus schema](../api/ubus/bbfdm.json) +## Example Configuration -### Ubus methods +```json +{ + "daemon": { + "enable": "1", + "service_name": "dhcpmngr", + "unified_daemon": false, + "services": [ + { + "parent_dm": "Device.", + "object": "DHCPv4" + }, + { + "parent_dm": "Device.", + "object": "DHCPv6" + } + ], + "config": { + "loglevel": "3" + } + } +} +``` -Following are the ubus methods exposed by `bbfdmd` main process: +### Explanation + +- **service_name** → `dhcpmngr` → `ubus` service name is `bbfdm.dhcpmngr` +- **Data model paths** → `Device.DHCPv4.` and `Device.DHCPv6.` +- **Protocol** → Both CWMP and USP since no restriction is defined in the JSON file. + +Any call to `bbfdm` with the path `Device.DHCPv4.XXXX` or `Device.DHCPv6.XXXX` will be directed to the `dhcpmngr` microservice. + +> **Note:** `bbfdmd` does not automatically reload services after updating the configuration. Higher-layer applications (e.g., `icwmp`, `obuspa`) use `bbf.config` to apply updates and reload services. + +--- + +## Input and Output Schema + +### Configuration +- `bbfdmd` configuration can be updated using `uci`: + - [bbfdm uci guide](../api/uci/bbfdm.md) + - [bbfdm uci schema](../api/uci/bbfdm.json) + +### Ubus Schema +- `bbfdmd` exposes a detailed schema for ubus methods: + - [bbfdm ubus guide](../api/ubus/bbfdm.md) + - [bbfdm ubus schema](../api/ubus/bbfdm.json) + +--- + +## Ubus Methods + +### Available Methods ```bash # ubus -v list bbfdm -'bbfdm' @b93b62aa - "get":{"path":"String","paths":"Array","maxdepth":"Integer","optional":"Table"} - "schema":{"path":"String","paths":"Array","first_level":"Boolean","optional":"Table"} - "instances":{"path":"String","paths":"Array","first_level":"Boolean","optional":"Table"} - "set":{"path":"String","value":"String","datatype":"String","obj_path":"Table","optional":"Table"} - "operate":{"command":"String","command_key":"String","input":"Table","optional":"Table"} - "add":{"path":"String","obj_path":"Table","optional":"Table"} - "del":{"path":"String","paths":"Array","optional":"Table"} - "notify_event":{"name":"String","input":"Array"} - "service":{} +'bbfdm' @7971a201 + "get":{"path":"String","value":"String","optional":"Table"} + "schema":{"path":"String","value":"String","optional":"Table"} + "instances":{"path":"String","value":"String","optional":"Table"} + "operate":{"path":"String","value":"String","optional":"Table"} + "set":{"path":"String","value":"String","optional":"Table"} + "add":{"path":"String","value":"String","optional":"Table"} + "del":{"path":"String","value":"String","optional":"Table"} + "services":{} ``` -> Note1: `optional` table are present in all methods and it supports below options: +### `optional` Table Options -```console -"optional":{"proto":"String", "format":"String"} +```json +"optional": {"proto": "String", "format": "String"} ``` - - `proto` in each method specify the data-model prototype('cwmp', 'usp') to use, if not provided default data-model will be used. +- **proto** → Specifies the data model protocol (`cwmp`, `usp`). Defaults to the standard model if not provided. +- **format** → Specifies the output format (`raw`, `pretty`). Defaults to `pretty` if not provided. - - `format` could be 'raw' or 'pretty', to specify the format to use as output, if not provided 'pretty' format will be used. +> **Note:** See the ubus schema document for more details. -> Note2: `first_level` true means only get next level objects and false means get all objects recursively +--- -> Note3: `maxdepth` is measured on max number of .(Dot) present in object name +## Debugging Tools -> Note4: Check ubus schema document for more details +### Command Line Interface (CLI) - -## Datamodel debugging tools - -To debug the datamodel objects/parameters, `bbfdmd` provides a command line interface, which can gets the data from an ubus object and then show it on the CLI. This command line tool is part of `bbfdmd` binary itself and can be accessed with command line argument option '-c' along with binary. +`bbfdmd` provides a CLI to debug the data model using the `-c` option: ```bash # bbfdmd -h Usage: bbfdmd [options] -options: - -c Run cli command - -l log verbosity value as per standard syslog - -h Displays this help - -# +Options: + -c Run CLI command + -l Log verbosity value (0-7) as per syslog + -h Displays this help ``` -If no command line option provided along with `bbfdmd` command then it starts in daemon mode. -In command (or CLI) mode, it supports interactively querying the data model and setting values in the configuration via the data model. + +If no options are provided, `bbfdmd` starts in daemon mode. + +### CLI Commands ```bash # bbfdmd -c help @@ -95,63 +149,28 @@ Valid commands: del [path-expr] instances [path-expr] schema [path-expr] -# ``` -To debug datamodel mapping/description code, user/developer can use below API to add debug logs +### Debugging Logs -```bash -BBF_ERR(MESSAGE, ...) -BBF_WARNING(MESSAGE, ...) -BBF_INFO(MESSAGE, ...) -BBF_DEBUG(MESSAGE, ...) +To enable debugging logs, use the following macros: + +```c +BBFDM_ERR(MESSAGE, ...) +BBFDM_WARNING(MESSAGE, ...) +BBFDM_INFO(MESSAGE, ...) +BBFDM_DEBUG(MESSAGE, ...) ``` -Above API logs gets logged using syslog, based on log_level defined in `bbfdm`. -To configure the log_level use `bbfdm.bbfdmd.loglevel` uci option. +Logs are written to `syslog` based on the `log_level` defined in the `bbfdm` configuration. +To configure the log level, use the `bbfdm.bbfdmd.loglevel` option. -## How to extend datamodel +--- -Although `bbfdm/iowrt` provides datamodels for major services, but still for deployment user might need to add some vendor extensions or needs to add the missing datamodel support. To do the same `bbfdm` or more precisely `libbfdm-api` provides the infrastructure to easily define a new datamodel tree. +## Notes -As per TR106 description, a datamodel is, "A hierarchical set of Objects, Parameters, Commands and/or Events that define the managed Objects accessible via a particular Agent." +1. `bbfdmd` does not handle RPC method output. +2. The actual arguments expected by `bbfdmd` may differ from the ones shown in the ubus schema because `bbfdmd` only routes the calls to the correct microservice. -Please check [TR106](https://www.broadband-forum.org/pdfs/tr-106-1-13-0.pdf) for more details about datamodel terminology. +--- -`bbfdm` provide the tools and utilities to further extend/overwrite/disable the datamodel using C-code or simply by using JSON datamodel definition. - -### JSON datamodel - -Pro: - - Easy to add (compilation not required) - - Least maintenance (Change in libbbfdm-api has minimal impact) - -Con: - - Can only support easy one to one mappings with uci and ubus - - Invalid plugin syntax might cause faults - -### C Based datamodel - -Pro: - - Support complex mapping and data sharing between nodes - - Lots of references available - - Tools available to auto-generate the template code - - All core operations supported - -Con: - - Moderate maintenance (Change in libbbfdm-api requires adaptation/alignment) - - -Both ways of extending datamodel covered at length with examples in following links -* [How to extend datamodel with C Code](How_to_extend_datamodel_with_C_Code.md) -* [How to extend datamodel with JSON](How_to_extend_datamodel_with_JSON.md) - -After creating the datamodel definition, it can be installed the help of `bbfdm.mk` APIs to run them from main `bbfdmd` instance or from micro-service instance. - -> Note: If a datamodel object added by a micro-service, all datamodel extensions below that path needed to be hanlded in the same micro-service. Like a wifi extension needed to be installed in wifidmd micro-service as a plugin. - -### How to choose C or JSON for datamodel extensions - -C/JSON both datamodel definition support defining all datamodel operations, but JSON should be used with simple datamodel deployments. - -If its requires to perform more than one step to retrieve data from lowerlayer, it is suggested to use C-Based datamodel definitions, as it gives more control over the data and its mapping, or simply put if JSON plugin does not meets the requirement of datamodel mapping use C-Based definition. diff --git a/docs/guide/dm-service.md b/docs/guide/dm-service.md index 6bc9249c..db115e3e 100644 --- a/docs/guide/dm-service.md +++ b/docs/guide/dm-service.md @@ -1,26 +1,32 @@ -# Data Model Micro-Service (dm-service +# Data Model Micro-Service (dm-service) -`dm-service` daemon is designed to expose a specific module or sub-tree of a data model as datamodel micro-service. +`dm-service` daemon is designed to expose a specific module or sub-tree of a data model as a datamodel micro-service. > Note: The command outputs shown in this document are examples and may vary depending on your device and configuration. ## Concepts and Workflow -`dm-service` daemon gets started by `/etc/init.d/bbfdm.services` service. This init script reads input from `bbfdm` UCI file, particularly from `micro_services` section. It then parses each micro-service configuration file located in `/etc/bbfdm/services/`. Each micro-service’s configuration, written in JSON, is used to start the service using the APIs provided by `libbbfdm-ubus` and `libbbfdm-api` libraries. +`dm-service` daemon is started by `/etc/init.d/bbfdm.services` service. This init script reads input from `bbfdm` UCI file, particularly from the `micro_services` section. It then parses each micro-service configuration file located in `/etc/bbfdm/services/`. Each micro-service’s configuration, written in JSON, is used to start the service using the APIs provided by `libbbfdm-ubus` and `libbbfdm-api` libraries. -`dm-service` daemon use `libbbfdm-api` library to traverse the datamodel tree defined by DotSo or JSON plugin located in `/usr/share/bbfdm/micro_services/$micro-service-name{.so,.json}` and its plugins defined in `/usr/share/bbfdm/micro_services/$micro-service-name/`. +`dm-service` daemon uses the `libbbfdm-api/legacy` library to traverse the datamodel tree defined by DotSo or JSON plugins located in `/usr/share/bbfdm/micro_services/$micro-service-name{.so,.json}` and its plugins defined in `/usr/share/bbfdm/micro_services/$micro-service-name/`. -`dm-service` daemon use `libbbfdm-ubus` library to expose datamodel over UBUS. +`dm-service` daemon uses the `libbbfdm-ubus` library to expose the datamodel over UBUS. -Datamodel micro-service is nothing but another `bbfdmd` instance running with smaller data sub-set, and can be identified at runtime by running a `ps` command +A datamodel micro-service is a data model instance running with a smaller data subset and can be identified at runtime by running a `ps` command: ```bash # ps|grep dm-service -12163 root 7664 S {dm_bulkdata} /usr/sbin/dm-service -m bulkdata -l 3 -12164 root 7620 S {dm_ddnsmngr} /usr/sbin/dm-service -m ddnsmngr -l 3 -12165 root 7736 S {dm_dhcpmngr} /usr/sbin/dm-service -m dhcpmngr -l 3 -12166 root 7760 S {dm_dnsmngr} /usr/sbin/dm-service -m dnsmngr -l 3 -12167 root 7800 S {dm_ethmngr} /usr/sbin/dm-service -m ethmngr -l 3 +11371 root 4904 S {dm_bridgemngr} /usr/sbin/dm-service -m bridgemngr -l 3 +11372 root 5052 S {dm_core} /usr/sbin/dm-service -m core -l 3 +11373 root 4856 S {dm_ddnsmngr} /usr/sbin/dm-service -m ddnsmngr -l 3 +11374 root 4848 S {dm_dhcp-on-boar} /usr/sbin/dm-service -m dhcp-on-boarding -l 3 +11375 root 4924 S {dm_dhcpmngr} /usr/sbin/dm-service -m dhcpmngr -l 3 +11376 root 4896 S {dm_dnsmngr} /usr/sbin/dm-service -m dnsmngr -l 3 +11377 root 4896 S {dm_firewallmngr} /usr/sbin/dm-service -m firewallmngr -l 3 +11378 root 4844 S {dm_gateway-info} /usr/sbin/dm-service -m gateway-info -l 3 +11379 root 4848 S {dm_gnx-ux-manag} /usr/sbin/dm-service -m gnx-ux-manager -l 3 +11380 root 4868 S {dm_hostmngr} /usr/sbin/dm-service -m hostmngr -l 3 +11381 root 4900 S {dm_icwmp} /usr/sbin/dm-service -m icwmp -l 3 ``` Each `dm-service` instance must be started with -m input to define its service name and run its module(sub-tree) datamodel. These micro-services exposed their own ubus objects. @@ -29,11 +35,14 @@ Each `dm-service` instance must be started with -m input to define its service n # ubus list bbfdm.* bbfdm.bridgemngr bbfdm.bulkdata +bbfdm.core bbfdm.ddnsmngr +bbfdm.dhcp-on-boarding bbfdm.dhcpmngr bbfdm.dnsmngr bbfdm.ethmngr bbfdm.firewallmngr +bbfdm.gateway-info ``` ## Setting Up a Datamodel as a Micro-Service @@ -43,53 +52,183 @@ Before starting a datamodel as a micro-service, ensure that the datamodel defini This file must include the following required fields: -- service_name: The name of the service. -- unified_daemon: A boolean indicating whether the service uses a unified daemon. -- services: An array containing sub-options: - - parent_dm: Specifies the parent data model. - - object: Defines the object type. - - proto: Indicates the protocol (e.g., cwmp, both). +- `enable`: Enables or disables the microservice. +- `service_name`: The name of the service. +- `unified_daemon`: A boolean indicating whether the service uses a unified daemon. +- `proto`: Indicates the protocol (e.g., cwmp, both) where the micro-service will be visible. +- `services`: An array containing multiple JSON objects, each providing information about the object that will be exposed from this micro-service and supports three possible options: + - `parent_dm`: Specifies the parent data model where the object will be linked. + - `object`: Defines the object or parameter name exposed from the micro-service. + - `proto`: Indicates the protocol (e.g., cwmp, both) where the object will be visible. +- `loglevel`: The log level used for the microservice -Once all required fields are defined, the datamodel can be registered and started when the `bbfdmd` is initialized +Once all required fields are defined, the datamodel can be registered and started when the `bbfdmd` is initialized. +```bash +# cat /etc/bbfdm/services/core.json +{ + "daemon": { + "enable": "1", + "service_name": "core", + "unified_daemon": false, + "services": [ + { + "parent_dm": "Device.", + "object": "LANConfigSecurity" + }, + { + "parent_dm": "Device.", + "object": "Schedules" + }, + { + "parent_dm": "Device.", + "object": "Security", + "proto": "cwmp" + }, + { + "parent_dm": "Device.", + "object": "PacketCaptureDiagnostics" + }, + { + "parent_dm": "Device.", + "object": "SelfTestDiagnostics" + }, + { + "parent_dm": "Device.", + "object": "Syslog" + }, + { + "parent_dm": "Device.", + "object": "X_IOWRT_EU_OpenVPN", + "proto": "usp" + }, + { + "parent_dm": "Device.", + "object": "RootDataModelVersion" + }, + { + "parent_dm": "Device.", + "object": "Reboot()" + }, + { + "parent_dm": "Device.", + "object": "FactoryReset()" + } + ], + "config": { + "loglevel": "3" + } + } +} +``` ## Verifying Micro-Service Registration After defining the datamodel, wait for the `bbfdmd` to start. Then, verify that the micro-service has been successfully registered to the core data model. You can do this by listing the registered services using the following command: ```bash -# ubus call bbfdm service +# ubus call bbfdm services { - "registered_service": [ + "registered_services": [ { - "name": "bbfdm.bridgemngr", - "parent_dm": "Device.", - "object": "Bridging", + "name": "bbfdm.icwmp", "proto": "both", - "unified_daemon": false + "unified_daemon": false, + "objects": [ + { + "parent_dm": "Device.", + "object": "ManagementServer", + "proto": "both" + }, + { + "parent_dm": "Device.", + "object": "CWMPManagementServer", + "proto": "usp" + }, + { + "parent_dm": "Device.", + "object": "XMPP", + "proto": "both" + } + ] }, { - "name": "bbfdm.bulkdata", - "parent_dm": "Device.", - "object": "BulkData", + "name": "bbfdm.ssdpd", + "proto": "both", + "unified_daemon": false, + "objects": [ + { + "parent_dm": "Device.", + "object": "UPnP", + "proto": "both" + } + ] + }, + { + "name": "bbfdm.tr104", + "proto": "both", + "unified_daemon": false, + "objects": [ + { + "parent_dm": "Device.Services.", + "object": "VoiceService", + "proto": "both" + } + ] + }, + { + "name": "bbfdm.obuspa", "proto": "cwmp", - "unified_daemon": true + "unified_daemon": false, + "objects": [ + { + "parent_dm": "Device.", + "object": "USPAgent", + "proto": "both" + }, + { + "parent_dm": "Device.", + "object": "MQTT", + "proto": "both" + }, + { + "parent_dm": "Device.", + "object": "STOMP", + "proto": "both" + } + ] }, { - "name": "bbfdm.ddnsmngr", - "parent_dm": "Device.", - "object": "DynamicDNS", + "name": "bbfdm.swmodd", "proto": "both", - "unified_daemon": false + "unified_daemon": false, + "objects": [ + { + "parent_dm": "Device.", + "object": "SoftwareModules", + "proto": "both" + } + ] + }, + { + "name": "bbfdm.dnsmngr", + "proto": "both", + "unified_daemon": false, + "objects": [ + { + "parent_dm": "Device.", + "object": "DNS", + "proto": "both" + } + ] } -} ``` + In this example: -- Each entry in `registered_service` represents a micro-service. +- Each entry in `registered_services` represents a micro-service. - Verify that your service is included in this list, and that its properties (`name`, `parent_dm`, `object`, `proto`, `unified_daemon`) are correctly configured. - ## Input and output Schema(s) `dm-service` is used to expose sub-tree using different ubus object, UBUS guide and schema for datamodel micro-services @@ -119,7 +258,6 @@ A typical micro-service input file looks like below: } } } - ``` ### Ubus methods @@ -127,20 +265,22 @@ A typical micro-service input file looks like below: Following are the UBUS methods exposed by `dm-service` process: ```bash -# ubus -v list bbfdm.Network -'bbfdm.Network' @9dc36737 - "get":{"path":"String","paths":"Array","maxdepth":"Integer","optional":"Table"} - "schema":{"path":"String","paths":"Array","first_level":"Boolean","optional":"Table"} - "instances":{"path":"String","paths":"Array","first_level":"Boolean","optional":"Table"} - "set":{"path":"String","value":"String","datatype":"String","obj_path":"Table","optional":"Table"} - "operate":{"command":"String","command_key":"String","input":"Table","optional":"Table"} - "add":{"path":"String","obj_path":"Table","optional":"Table"} - "del":{"path":"String","paths":"Array","optional":"Table"} +# ubus -v list bbfdm.netmngr +'bbfdm.netmngr' @e93fc046 + "get":{"path":"String","optional":"Table"} + "schema":{"path":"String","first_level":"Boolean","optional":"Table"} + "instances":{"path":"String","optional":"Table"} + "set":{"path":"String","value":"String","datatype":"String","obj_path":"Table","optional":"Table"} + "operate":{"path":"String","command_key":"String","input":"Table","optional":"Table"} + "add":{"path":"String","obj_path":"Table","optional":"Table"} + "del":{"path":"String","paths":"Array","optional":"Table"} + "reference_path":{"path":"String","optional":"Table"} + "reference_value":{"path":"String","optional":"Table"} ``` > Note1: `optional` table are present in all methods and it supports below options: -```console +```json "optional":{"proto":"String", "format":"String"} ``` @@ -150,14 +290,12 @@ Following are the UBUS methods exposed by `dm-service` process: > Note2: `first_level` true means only get next level objects and false means get all objects recursively -> Note3: `maxdepth` is measured on max number of .(Dot) present in object name - > Note4: Check ubus schema document for more details ## Pros and Cons of Data Model Micro-Service -Data model micro-service is nothing but running a partial datamodel sub-set with another instance of `bbfdmd` binary. +Data model micro-service is running a partial datamodel sub-set. Benefit: - Instead of having a huge datamodel tree, it split the tree based on modules, which reduce the cost of operation on the tree @@ -207,7 +345,7 @@ Micro-service approach, disintegrate the plugins further and run them as individ ## Datamodel debugging tools -To configure the log_level in micro-service, update the `loglevel` module json file, +To configure the log_level in a micro-service, update the `loglevel` value in the module JSON file: ```json # cat /etc/bbfdm/services/netmngr.json @@ -245,4 +383,14 @@ To configure the log_level in micro-service, update the `loglevel` module json f } ``` -and then restart the bbfdm.services +Then restart `bbfdm.services` for that specific micro-service: + +```bash +/etc/init.d/bbfdm.services restart netmngr +``` + +To restart all micro-services: + +```bash +/etc/init.d/bbfdm.services restart +``` diff --git a/docs/guide/extend_datamodel.md b/docs/guide/extend_datamodel.md new file mode 100644 index 00000000..4ddef98e --- /dev/null +++ b/docs/guide/extend_datamodel.md @@ -0,0 +1,45 @@ +# How to extend datamodel + +Although `bbfdm/iowrt` provides datamodels for major services, but still for deployment user might need to add some vendor extensions or needs to add the missing datamodel support. To do the same `bbfdm.XXXX` or more precisely `libbfdm-api/legacy` provides the infrastructure to easily define a new datamodel tree. + +As per TR106 description, a datamodel is, "A hierarchical set of Objects, Parameters, Commands and/or Events that define the managed Objects accessible via a particular Agent." + +Please check [TR106](https://www.broadband-forum.org/pdfs/tr-106-1-13-0.pdf) for more details about datamodel terminology. + +`bbfdm` provide the tools and utilities to further extend/overwrite/disable the datamodel using C-code or simply by using JSON datamodel definition. + +## JSON datamodel + +Pro: + - Easy to add (compilation not required) + - Least maintenance (Change in libbbfdm-api has minimal impact) + +Con: + - Can only support easy one to one mappings with uci and ubus + - Invalid plugin syntax might cause faults + +## C Based datamodel + +Pro: + - Support complex mapping and data sharing between nodes + - Lots of references available + - Tools available to auto-generate the template code + - All core operations supported + +Con: + - Moderate maintenance (Change in libbbfdm-api requires adaptation/alignment) + + +Both ways of extending datamodel covered at length with examples in following links +* [How to extend datamodel with C Code](How_to_extend_datamodel_with_C_Code.md) +* [How to extend datamodel with JSON](How_to_extend_datamodel_with_JSON.md) + +After creating the datamodel definition, it can be installed the help of `bbfdm.mk` APIs to run them from any specific micro-service instance or with a new micro-service. + +> Note: If the new data model added for specific micro service, all datamodel extension need to be hanlded in the same micro-service. Like a wifi extension needed to be installed in wifidmd micro-service as a plugin. + +# How to choose C or JSON for datamodel extensions + +C/JSON both datamodel definition support defining all datamodel operations, but JSON should be used with simple datamodel deployments. + +If its requires to perform more than one step to retrieve data from lowerlayer, it is suggested to use C-Based datamodel definitions, as it gives more control over the data and its mapping, or simply put if JSON plugin does not meets the requirement of datamodel mapping use C-Based definition. diff --git a/docs/guide/libbbfdm-api.md b/docs/guide/libbbfdm-api-legacy.md similarity index 95% rename from docs/guide/libbbfdm-api.md rename to docs/guide/libbbfdm-api-legacy.md index 0e6fad86..f15b60a3 100644 --- a/docs/guide/libbbfdm-api.md +++ b/docs/guide/libbbfdm-api-legacy.md @@ -1,8 +1,8 @@ # API guide and usages -`libbbfdm-api` provides API to define datamodel objects as well as it also provides APIs to traverse the datamodel definitions. +`libbbfdm-api-legacy` provides API to define datamodel objects as well as it also provides APIs to traverse the datamodel definitions. -Most used datamodel APIs described in [libbbfdm_api.h](../../libbbfdm-api/include/libbbfdm_api.h) +Most used datamodel APIs described in [libbbfdm_api.h](../../libbbfdm-api/legacy/include/libbbfdm_api.h) Following is the list of APIs used by bbfdmd for tree traversal: @@ -145,7 +145,7 @@ return # Deprecated/removed APIs and user defined datatypes -To support new feature sometimes old APIs provided by libbbfdm-api library needs to be updated, this guide provides a better context to the migration. +To support new feature sometimes old APIs provided by `libbbfdm-api-legacy` library needs to be updated, this guide provides a better context to the migration. Following table has APIs/datatypes which are now deprecated: @@ -156,7 +156,7 @@ Following table has APIs/datatypes which are now deprecated: | stucture | `dmmap_dup` | `dm_data` | Replaced to support the extension for Obj/Param/Operate using JSON plugin | -Following table has list of APIs/datatypes which no longer exists in libbbfdm-api, along with new revised APIs replacement: +Following table has list of APIs/datatypes which no longer exists in `libbbfdm-api-legacy`, along with new revised APIs replacement: | Type | Removed API | New API | Comment | | -------- | ---------------------------------- | ------------------------------------ | -------------------------------------- | diff --git a/docs/guide/libbbfdm-api-version-2.md b/docs/guide/libbbfdm-api-version-2.md new file mode 100644 index 00000000..4a75b377 --- /dev/null +++ b/docs/guide/libbbfdm-api-version-2.md @@ -0,0 +1,19 @@ +# API Guide and Usage + +`libbbfdm-api-version-2` is the latest version of the `libbbfdm-api`, offering a streamlined set of generic APIs that simplify interaction with the data model, both internally and externally. This version manages memory allocation internally, reducing complexity and making it easier to integrate into various applications. + +## Key Improvements + +- **Simplified Memory Management:** No need for manual memory handling. +- **Consistent API Calls:** Unified and easier-to-use interfaces. +- **Enhanced Flexibility:** Suitable for both internal and external data model calls. + +## API Overview + +Detailed information about each API’s functionality is available in the corresponding header files: + +- **[Global APIs](../../libbbfdm-api/version-2/bbfdm_api.h)** +- **[UCI APIs](../../libbbfdm-api/version-2/bbfdm_uci.h)** +- **[UBUS APIs](../../libbbfdm-api/version-2/bbfdm_ubus.h)** +- **[Memory APIs](../../libbbfdm-api/version-2/bbfdm_mem.h)** +- **[System APIs](../../libbbfdm-api/version-2/bbfdm_ubus.h)** diff --git a/docs/guide/libbbfdm-ubus.md b/docs/guide/libbbfdm-ubus.md index 74dfa72c..ed07a2fd 100644 --- a/docs/guide/libbbfdm-ubus.md +++ b/docs/guide/libbbfdm-ubus.md @@ -1,127 +1,122 @@ # LIBBBFDM Ubus (libbbfdm-ubus) -`libbbfdm-ubus` is a library that provides APIs to expose datamodel over ubus. It is used to manage various data models in different micro-services and higher-level applications. +`libbbfdm-ubus` is a library that provides APIs to expose the data model over ubus as microservices. It is used to manage various data models in different microservices and higher-level applications. ## Use Cases -`libbbfdm-ubus` library can be used by: +The `libbbfdm-ubus` library can be used by: - - `bbfdmd`: to expose the core data model - - `dm-service`: to expose a sub-data model as micro-service, example: [Netmngr](https://dev.iopsys.eu/network/netmngr/-/blob/devel/src/net_plugin.c) - - Higher-level applications(unified daemon): to expose custom data models as microservices within their daemon, example: [Timemngr](https://dev.iopsys.eu/bbf/timemngr/-/blob/devel/src/main.c) +- `dm-service`: To expose a sub-data model as a microservice, e.g., [Network Manager](https://dev.iopsys.eu/network/netmngr/-/blob/devel/src/net_plugin.c), [Bridge Manager](https://dev.iopsys.eu/network/bridgemngr/-/blob/devel/src/driver_vlan_backend/bridging.c) +- Higher-level applications (unified daemon): To expose custom data models as microservices within their daemon, e.g., [Time Manager](https://dev.iopsys.eu/bbf/timemngr/-/blob/devel/src/main.c), [System Manager](https://dev.iopsys.eu/system/sysmngr/-/blob/devel/src/sysmngr.c) ## libbbfdm-ubus APIs -The following APIs are provided by `libbbfdm-ubus` to expose data model over ubus: +The following APIs are provided by `libbbfdm-ubus` to expose the data model over ubus: ### bbfdm_ubus_regiter_init -This method is used to initialize the bbfdm_context structure object and register ubus data model methods. +This method initializes the `bbfdm_context` structure object and registers ubus data model methods. -``` +```c int bbfdm_ubus_regiter_init(struct bbfdm_context *bbfdm_ctx) -inputs - struct bbfdm_context *bbfdm_ctx - pointer to struct bbfdm_context structure to be initialized. +Inputs: + struct bbfdm_context *bbfdm_ctx + Pointer to the `bbfdm_context` structure to be initialized. -return - int fault - returns 0 on success, or an error code if the registration fails. +Returns: + int fault + Returns 0 on success, or an error code if the registration fails. ``` - ### bbfdm_ubus_regiter_free -This method is used to free the bbfdm_context structure object +This method frees the `bbfdm_context` structure object. -``` +```c int bbfdm_ubus_regiter_free(struct bbfdm_context *bbfdm_ctx) -inputs - struct bbfdm_context *bbfdm_ctx - pointer to struct bbfdm_context structure to be freed. +Inputs: + struct bbfdm_context *bbfdm_ctx + Pointer to the `bbfdm_context` structure to be freed. -return - int fault - returns 0 on success, or an error code if freeing fails. +Returns: + int fault + Returns 0 on success, or an error code if freeing fails. ``` - ### bbfdm_ubus_set_service_name -This method is used the service name for the daemon running as a microservice +This method sets the service name for the daemon running as a microservice. -``` +```c void bbfdm_ubus_set_service_name(struct bbfdm_context *bbfdm_ctx, const char *srv_name) -input - struct bbfdm_context *bbfdm_ctx - pointer to struct bbfdm_context structure +Inputs: + struct bbfdm_context *bbfdm_ctx + Pointer to the `bbfdm_context` structure. - const char *srv_name - pointer to service name to set - -return - None + const char *srv_name + Pointer to the service name to set. + +Returns: + None ``` - ### bbfdm_ubus_set_log_level -This method is used to set the log level according to the standard syslog levels +This method sets the log level according to the standard syslog levels. -``` +```c void bbfdm_ubus_set_log_level(int log_level) -input - int log_level - desired log level to set - -return - None -``` +Inputs: + int log_level + Desired log level to set. +Returns: + None +``` ### bbfdm_ubus_load_data_model -This method is used to load an internal data model, allowing you to use an internal model instead of external plugins (e.g., DotSo or JSON). +This method loads an internal data model, allowing you to use an internal model instead of external plugins (e.g., DotSo or JSON). -``` +```c void bbfdm_ubus_load_data_model(DM_MAP_OBJ *DynamicObj) -input - DM_MAP_OBJ *DynamicObj - pointer to internal data model - -return - None +Inputs: + DM_MAP_OBJ *DynamicObj + Pointer to the internal data model. + +Returns: + None ``` -## libbbfdm-ubus methods +## libbbfdm-ubus Methods Following are the ubus methods exposed by `libbbfdm-ubus` when registering a new module: ```bash -# ubus -v list bbfdm -bbfdm' @b93b62aa - "get":{"path":"String","paths":"Array","maxdepth":"Integer","optional":"Table"} - "schema":{"path":"String","paths":"Array","first_level":"Boolean","optional":"Table"} - "instances":{"path":"String","paths":"Array","first_level":"Boolean","optional":"Table"} +# ubus -v list bbfdm.sysmngr +'bbfdm.sysmngr' @6931a0bb + "get":{"path":"String","optional":"Table"} + "schema":{"path":"String","first_level":"Boolean","optional":"Table"} + "instances":{"path":"String","optional":"Table"} "set":{"path":"String","value":"String","datatype":"String","obj_path":"Table","optional":"Table"} - "operate":{"command":"String","command_key":"String","input":"Table","optional":"Table"} + "operate":{"path":"String","command_key":"String","input":"Table","optional":"Table"} "add":{"path":"String","obj_path":"Table","optional":"Table"} "del":{"path":"String","paths":"Array","optional":"Table"} - "notify_event":{"name":"String","input":"Array"} - "service":{} + "reference_path":{"path":"String","optional":"Table"} + "reference_value":{"path":"String","optional":"Table"} ``` -## libbbfdm-ubus example(s) +## libbbfdm-ubus Examples -1. The requested value is correct as per TR181 standard, but there is a limitation in the device. +### 1. The requested value is correct as per the TR181 standard, but there is a limitation in the device. -```console -root@iopsys:~# ubus call bbfdm set '{"path":"Device.Firewall.Config", "value":"High"}' +```bash +root@iowrt:~# ubus call bbfdm.firewallmngr set '{"path":"Device.Firewall.Config", "value":"High"}' { "results": [ { @@ -133,10 +128,10 @@ root@iopsys:~# ubus call bbfdm set '{"path":"Device.Firewall.Config", "value":"H } ``` -2. The requested value is outside the allowed range. +### 2. The requested value is outside the allowed range. -```console -root@iopsys:~# ubus call bbfdm set '{"path":"Device.Firewall.Chain.1.Rule.9.DestPort", "value":"123456"}' +```bash +root@iowrt:~# ubus call bbfdm.firewallmngr set '{"path":"Device.Firewall.Chain.1.Rule.9.DestPort", "value":"123456"}' { "results": [ { @@ -148,26 +143,30 @@ root@iopsys:~# ubus call bbfdm set '{"path":"Device.Firewall.Chain.1.Rule.9.Dest } ``` -3. Some arguments should be defined to perform the requested operation. +### 3. Some arguments should be defined to perform the requested operation. -```console -root@iopsys:~# ubus call bbfdm operate '{"command":"Device.IP.Diagnostics.IPPing()", "command_key":"ipping_test", "input":{}}' +```bash +root@iowrt:~# ubus call bbfdm.netmngr operate '{"path":"Device.IP.Diagnostics.IPPing()", "command_key":"ipping_test", "input":{}}' { "results": [ { "path": "Device.IP.Diagnostics.IPPing()", "data": "ipping_test", - "fault": 7004, - "fault_msg": "IPPing: 'Host' input should be defined" + "output": [ + { + "fault": 7004, + "IPPing: 'Host' input should be defined" + } + ] } ] } ``` -4. The path parameter value must start with 'Device.'. The command below doesn't have Device before path "Users.User." +### 4. The path parameter value must start with 'Device.'. The command below doesn't have Device before path "Users.User." ```console -root@iopsys:~# ubus call bbfdm get '{"path":"Users.User.", "optional": {"format":"raw", "proto":"usp"}}' +root@iowrt:~# ubus call bbfdm.usermngr get '{"path":"Users.User.", "optional": {"format":"raw", "proto":"usp"}}' { "results": [ { @@ -181,50 +180,22 @@ root@iopsys:~# ubus call bbfdm get '{"path":"Users.User.", "optional": {"format" These fault messages defined in datamodel handlers, users can add such fault message using `bbfdm_set_fault_message` libbbfdm-api's API, if no specific fault message defined for particular obj/param, datamodel returns standard error messages that are defined in CWMP and USP protocols as the fault message value. -### Fault handling +## Fault Handling -To indicate a fault and source of fault, `libbbfdm-ubus` provides `fault` along with `fault_msg` in the response in case of faults, which then handled by higher layer applications (i.e icwmp, obuspa). +To indicate a fault and its source, `libbbfdm-ubus` provides `fault` along with `fault_msg` in the response in case of faults, which are then handled by higher-layer applications (e.g., icwmp, obuspa). -This provides a clear inside on the root cause of the fault, and based on `fault_msg` it's easily to understand what the issue is and how to fix it and find out the limitations(if there are any on the device). +This provides a clear insight into the root cause of the fault. Based on `fault_msg`, it’s easy to understand the issue, how to fix it, and identify limitations (if any) in the device. -##### Errors Codes +### Error Codes -| Error Code | Meaning | -|------------|--------------------------------------------------------------| -| 7003 | Message failed due to an internal error. | -| 7004 | Message failed due to invalid values in the request elements and/or failure to update one or more parameters during Add or Set requests. | -| 7005 | Message failed due to memory or processing limitations. | -| 7008 | Requested path was invalid or a reference was invalid. | -| 7010 | Requested Path Name associated with this ParamError did not match any instantiated parameters. | -| 7011 | Unable to convert string value to correct data type. | -| 7012 | Out of range or invalid enumeration. | -| 7022 | Command failed to operate. | -| 7026 | Path is not present in the data model schema. | - - -## Parallel calls over Ubus - -Some datamodel operations takes less time to execute compared to other, like -- Get on sub-set of datamodel or an individual datamodel parameter takes very less, where as -- Get on complete Device. and Async operate commands takes much longer - -executing/serializing operations simplifies the code from developer perspective, but its not suitable for deployments. To make it suitable `bbfdmd` support parallel calls. - -- All datamodel `operate` commands are running in parallel - -example(s): - -```console -root@iopsys:~# time ubus call bbfdm get '{"path":"Device."}' >/dev/null & -root@iopsys:~# time ubus call bbfdm get '{"path":"Device.Users."}' >/dev/null -real 0m 0.07s -user 0m 0.00s -sys 0m 0.00s -root@iopsys:~# -real 0m 1.86s -user 0m 0.05s -sys 0m 0.00s - -[1]+ Done time ubus call bbfdm get "{\"path\":\"Device.\"}" >/dev/null -root@iopsys:~# -``` +| Error Code | Meaning | +|------------|---------| +| 7003 | Message failed due to an internal error. | +| 7004 | Message failed due to invalid values in the request elements and/or failure to update one or more parameters during Add or Set requests. | +| 7005 | Message failed due to memory or processing limitations. | +| 7008 | Requested path was invalid or a reference was invalid. | +| 7010 | Requested Path Name associated with this ParamError did not match any instantiated parameters. | +| 7011 | Unable to convert string value to correct data type. | +| 7012 | Out of range or invalid enumeration. | +| 7022 | Command failed to operate. | +| 7026 | Path is not present in the data model schema. | diff --git a/tools/README.md b/tools/README.md index 4efb4524..bf8955bd 100644 --- a/tools/README.md +++ b/tools/README.md @@ -96,7 +96,7 @@ $ ./tools/validate_json_plugin.py test/files/etc/bbfdm/json/TEST.json $ ./tools/validate_json_plugin.py tools/datamodel.json ``` -More examples available in [this path](../test/files/usr/share/bbfdm/plugins). +More examples available in [this path](../test/files/usr/share/bbfdm/micro_services/core). ### generate_dm.sh