From 7cdea20a2de6bb03eb01f6335e8d4d9660292fee Mon Sep 17 00:00:00 2001 From: Vivek Kumar Dutta Date: Mon, 8 Jul 2024 11:55:18 +0530 Subject: [PATCH] docs: cleanup and update --- .gitignore | 5 - README.md | 160 +- docs/api/ubus/.pages | 4 - {schemas => docs/api}/ubus/bbfdm.json | 0 docs/api/ubus/bbfdm_micro_service.json | 793 +++++++ docs/api/ubus/bbfdm_micro_service.md | 2066 +++++++++++++++++ {schemas => docs/api}/uci/bbfdm.json | 42 +- .../How_to_extend_datamodel_with_C_Code.md | 281 +++ ...d => How_to_extend_datamodel_with_JSON.md} | 530 ++++- docs/guide/bbfdmd.md | 499 +++- docs/guide/bbfdmd_dm_integration.md | 213 -- docs/guide/bbfdmd_event.md | 70 - docs/guide/bbfdmd_ubus_errors.md | 197 -- docs/guide/bbfdmd_ubus_methods.md | 1259 ---------- docs/guide/bbfdmd_ubus_parallel_call.md | 20 - docs/guide/libbbfdm-api.md | 196 ++ .../libbbfdm-api_datamodel_as_microservice.md | 134 -- docs/guide/libbbfdm-api_dynamic_dm.md | 425 ---- docs/guide/libbbfdm-api_json_plugin_v2.md | 97 - ...bfdm-api_migrate_deprecated_removed_api.md | 55 - .../guide/libbbfdm-api_obj_param_extension.md | 167 -- docs/guide/libbbfdm-api_vendor.md | 82 - gitlab-ci/bbfdmd-functional-test.sh | 2 +- libbbfdm/CMakeLists.txt | 9 +- libbbfdm/dmtree/vendor/iopsys/vendor.json | 1741 -------------- tools/bbf_common.py | 8 +- tools/generate_dm.py | 10 +- tools/tools_input.json | 7 +- utilities/README.md | 80 + .../bbfdm}/scripts/bbf_activate_handler.sh | 0 .../files/usr/share/bbfdm}/scripts/bbf_api | 0 .../share/bbfdm}/scripts/bbf_check_idle.sh | 0 32 files changed, 4406 insertions(+), 4746 deletions(-) delete mode 100644 docs/api/ubus/.pages rename {schemas => docs/api}/ubus/bbfdm.json (100%) create mode 100644 docs/api/ubus/bbfdm_micro_service.json create mode 100644 docs/api/ubus/bbfdm_micro_service.md rename {schemas => docs/api}/uci/bbfdm.json (71%) create mode 100644 docs/guide/How_to_extend_datamodel_with_C_Code.md rename docs/guide/{libbbfdm-api_json_plugin_v1.md => How_to_extend_datamodel_with_JSON.md} (51%) delete mode 100644 docs/guide/bbfdmd_dm_integration.md delete mode 100644 docs/guide/bbfdmd_event.md delete mode 100644 docs/guide/bbfdmd_ubus_errors.md delete mode 100644 docs/guide/bbfdmd_ubus_methods.md delete mode 100644 docs/guide/bbfdmd_ubus_parallel_call.md create mode 100644 docs/guide/libbbfdm-api.md delete mode 100644 docs/guide/libbbfdm-api_datamodel_as_microservice.md delete mode 100644 docs/guide/libbbfdm-api_dynamic_dm.md delete mode 100644 docs/guide/libbbfdm-api_json_plugin_v2.md delete mode 100644 docs/guide/libbbfdm-api_migrate_deprecated_removed_api.md delete mode 100644 docs/guide/libbbfdm-api_obj_param_extension.md delete mode 100644 docs/guide/libbbfdm-api_vendor.md create mode 100644 utilities/README.md rename {libbbfdm => utilities/files/usr/share/bbfdm}/scripts/bbf_activate_handler.sh (100%) rename {libbbfdm => utilities/files/usr/share/bbfdm}/scripts/bbf_api (100%) rename {libbbfdm => utilities/files/usr/share/bbfdm}/scripts/bbf_check_idle.sh (100%) diff --git a/.gitignore b/.gitignore index 94d23a2a..c6958c71 100644 --- a/.gitignore +++ b/.gitignore @@ -1,12 +1,7 @@ -CMakeFiles -CMakeCache.txt -Makefile install_manifest.txt -*.cmake *.o *.so bbfdmd/ubus/bbfdmd -docs/index.md __pycache__ out /datamodel diff --git a/README.md b/README.md index dc6e2df7..b0c7c13a 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,14 @@ # BroadBand Forum Data Models (BBFDM) -`bbfdm` is a 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 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` has three main components: -| Component | Description | -| ---------- | ------------------------------------------------- | -| bbfdmd | A daemon to expose data model objects over ubus in pretty and raw format | -| libbbfdm-api | A shared library which provides API to build and parse datamodel tree, it also provides API to create datamodel extensions using shared DotSo plugin, or with JSON Plugin. | -| libbbfdm | A datamodel tree/library build with libbbfdm-api, it includes core TR181 and related datamodel | +| Component | Description | +| ------------ | ------------------------------------------------- | +| bbfdmd | A daemon to expose data model objects over ubus | +| libbbfdm-api | API library to create and parse datamodel tree | +| libbbfdm | Minimal TR181 datamodel definition | ## Directory Structure @@ -16,101 +16,67 @@ `bbfdm` package is structured as follow: ```bash -├── bbfdmd -├── docs -├── libbbfdm-api -├── libbbfdm -│   ├── dmtree -│   │   ├── json -│   │   ├── tr181 -│   │   ├── vendor -│   ├── scripts -└── tools +├── bbfdmd -- This directory contains daemon code to expose the datamodel tree on northbound +│   └── ubus - Daemon to expose datamodel over ubus +├── docs -- More detailed explanation of datamodel and user guide +├── gitlab-ci -- Used for CI/CD pipeline test +├── libbbfdm -- Minimal TR181 datamodel implementation +├── libbbfdm-api -- API library to create datamodel definition and parse the datamodel definition to form a datamodel tree +├── 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` folder which contains the source code of bbfdm deamon. -More explanation on how this daemon works and all supported methods are presented in this file [BBFDMD](./docs/guide/bbfdmd.md) - -- `libbbfdm` folder which contains the different data models supported by iopsys - - - `dmtree` folder which includes all supported Data Models and vendor extension objects. It contains 6 folders: - - - `tr181` folder : TR-181 Data Model files - - - `vendor` folder : Vendor Data Model files - - - `json` folder : Data Model JSON file - - - `scripts` folder which contains bbf APIs used to run the different diagnostics scripts. - -- `libbbfdm-api` folder which contains the source code of all API functions (UCI, Ubus, JSON, CLI and memory management). These API are used for GET/SET/ADD/Delete/Operate calls which can be called in internal or external packages. -All APIs exposed by libbbfdm-api are presented in this header file [libbbfdm_api.h](./libbbfdm-api/include/libbbfdm_api.h). - -- `tools` folder which contains some tools to generate Data Model in C, JSON, XML and Excel format. -All supported tools are presented in this file[BBFDM Tools](./tools/README.md) - -- `docs` folder which contains all documentation files. - - -## Design -* [BBFDMD Design](./docs/guide/bbfdmd.md) -* [Datamodel extension using JSON plugin](./docs/guide/libbbfdm-api_json_plugin_v1.md) -* [Datamodel Plugins and Microservice](./docs/guide/libbbfdm-api_datamodel_as_microservice.md) -* [BBFDM Tools](./tools/README.md) - ## Important Topics -* [Add support of a new Object/Parameter](./docs/guide/libbbfdm-api_obj_param_extension.md) -* [How to add new vendor](./docs/guide/libbbfdm-api_vendor.md) -* [Dynamic Object/Parameter/Operate/Event](./docs/guide/libbbfdm-api_dynamic_dm.md) + +* [BBFDMD Design](./docs/guide/bbfdmd.md) +* [API Documentation](./docs/guide/libbbfdm-api.md) +* [Tools](./tools/README.md) +* [Utilities](./utilities/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) + +### Datamodel related topics + * [Design for firmware activation](./docs/guide/libbbfdm_DeviceInfo_FirmwareImage.md) -* [Explain the different Network Deployment Scenarios](./docs/guide/network_depoyment_scenarios.md) -* [Explain Policy Based Routing Management](./docs/guide/libbbfdm_Routing.md) +* [Different Network Deployment Scenarios using Datamodels](./docs/guide/network_depoyment_scenarios.md) +* [GRE datamodel details ](./docs/guide/libbbfdm_GRE.md) +* [IP datamodel details](./docs/guide/libbbfdm_IP_Interface.md) + +### 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) +* [JSON Plugin Validator](https://dev.iopsys.eu/feed/iopsys/-/blob/devel/bbfdm/tools/validate_plugins.py) ## Additional datamodel objects -| Datamodel | Package | Link | -| ---------------------------------------- | -------------- | -------------------------------------------- | -| Device.BulkData. | bulkdata | https://dev.iopsys.eu/bbf/bulkdata.git | -| Device.ManagementServer. | icwmp | https://dev.iopsys.eu/bbf/icwmp.git | -| Device.CWMPManagementServer. | icwmp | https://dev.iopsys.eu/bbf/icwmp.git | -| Device.IP.Diagnostics.UDPEchoConfig. | udpecho-server | https://dev.iopsys.eu/bbf/udpecho.git | -| Device.IP.Diagnostics.UDPEchoDiagnostics.| udpecho-client | https://dev.iopsys.eu/bbf/udpecho.git | -| Device.IP.Interface.{i}.TWAMPReflector. | twamp | https://dev.iopsys.eu/bbf/twamp-light.git | -| Device.XMPP. | xmppc | https://dev.iopsys.eu/bbf/xmppc.git | -| Device.USPAgent. | obuspa | https://dev.iopsys.eu/bbf/obuspa.git | -| STUN parameters | stunc | https://dev.iopsys.eu/bbf/stunc.git | -| Device.XPON. | ponmngr | https://dev.iopsys.eu/hal/ponmngr.git | -| Device.UPNP. | ssdpd | https://github.com/miniupnp/miniupnp.git | -| Device.Users. | usermngr | https://dev.iopsys.eu/bbf/usermngr.git | -| Device.PeriodicStatistics. | periodicstats | https://dev.iopsys.eu/bbf/periodicstats.git | -| Device.SoftwareModules. | swmodd | https://dev.iopsys.eu/lcm/swmodd.git | -| Device.Time. | timemngr | https://dev.iopsys.eu/bbf/timemngr.git | -| Device.DynamicDNS. | ddnsmngr | https://dev.iopsys.eu/bbf/ddnsmngr.git | -| Device.Hosts. | hostmngr | https://dev.iopsys.eu/iopsys/hostmngr.git | -| Device.Services.VoiceService. | tr104 | https://dev.iopsys.eu/voice/tr104.git | -| Device.Firewall. | firewallmngr | https://dev.iopsys.eu/network/firewallmngr | -| Device.NAT. | firewallmngr | https://dev.iopsys.eu/network/firewallmngr | -| Device.NAT.PortTrigger. | port-trigger | https://dev.iopsys.eu/network/port-trigger.git | -| Device.DNS. | dnsmngr | https://dev.iopsys.eu/network/dnsmngr.git | -| Device.DHCPv4. | dhcpmngr | https://dev.iopsys.eu/network/dhcpmngr.git | -| Device.DHCPv6. | dhcpmngr | https://dev.iopsys.eu/network/dhcpmngr.git | -| Device.DSL. | dslmngr | https://dev.iopsys.eu/hal/dslmngr.git | -| Device.FAST. | dslmngr | https://dev.iopsys.eu/hal/dslmngr.git | -| Device.ATM. | dslmngr | https://dev.iopsys.eu/hal/dslmngr.git | -| Device.PTM. | dslmngr | https://dev.iopsys.eu/hal/dslmngr.git | -| Device.Ethernet. | ethmngr | https://dev.iopsys.eu/hal/ethmngr.git | -| Device.QoS. | qosmngr | https://dev.iopsys.eu/hal/qosmngr.git | -| Device.SSH. | sshmngr | https://dev.iopsys.eu/network/sshmngr.git | -| Device.WiFi. | wifidmd | https://dev.iopsys.eu/bbf/wifidmd.git | -| Device.USB. | usbmngr | https://dev.iopsys.eu/system/usbmngr.git | -| Device.Bridging. | bridgemngr | https://dev.iopsys.eu/network/bridgemngr.git | -| Device.IP.Diagnostics. | tr143 | https://dev.iopsys.eu/bbf/tr143d.git | -| Device.IP.Diagnostics.IPLayerCapacityMetrics. | tr471 | https://dev.iopsys.eu/bbf/tr471d.git | -| Device.X_IOPSYS_EU_IGMP. | mcastmngr | https://dev.iopsys.eu/hal/mcastmngr.git | -| Device.X_IOPSYS_EU_MLD. | mcastmngr | https://dev.iopsys.eu/hal/mcastmngr.git | -| Device.PacketCaptureDiagnostics. | packet-capture-diagnostics | https://dev.iopsys.eu/bbf/packet-capture-diagnostics.git | -| Device.SelfTestDiagnostics. | self-diagnostics | https://dev.iopsys.eu/feed/iopsys.git | -| Device.UPnP. | ssdpd | https://dev.iopsys.eu/feed/iopsys.git | -| Device.IEEE1905. | ieee1905 | https://dev.iopsys.eu/multi-ap/ieee1905.git | -| Device.MQTT.Broker. | mosquitto | https://dev.iopsys.eu/feed/openwrt-packages.git | -| Device.X_IOPSYS_EU_OpenVPN. | openvpn | https://dev.iopsys.eu/feed/openwrt-packages.git | +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) + +## Dependencies + +### Build-Time Dependencies + +To successfully build bbfdmd, following libraries are needed: + +| Dependency | Link | License | +| ------------ | ------------------------------------------- | -------- | +| libuci | https://git.openwrt.org/project/uci.git | LGPL 2.1 | +| libubox | https://git.openwrt.org/project/libubox.git | BSD | +| libubus | https://git.openwrt.org/project/ubus.git | LGPL 2.1 | +| libjson-c | https://s3.amazonaws.com/json-c_releases | MIT | +| libbbfdm-api | https://dev.iopsys.eu/bbf/bbfdm.git | BSD-3 | +| libbbfdm | https://dev.iopsys.eu/bbf/bbfdm.git | BSD-3 | +| jq | https://github.com/stedolan/jq.git | BSD | + + +### 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 | https://dev.iopsys.eu/bbf/bbfdm.git | BSD-3 | +| jq | https://github.com/stedolan/jq.git | BSD | diff --git a/docs/api/ubus/.pages b/docs/api/ubus/.pages deleted file mode 100644 index 632e4a21..00000000 --- a/docs/api/ubus/.pages +++ /dev/null @@ -1,4 +0,0 @@ -title: "BBFDM" - -nav: - - "..." diff --git a/schemas/ubus/bbfdm.json b/docs/api/ubus/bbfdm.json similarity index 100% rename from schemas/ubus/bbfdm.json rename to docs/api/ubus/bbfdm.json diff --git a/docs/api/ubus/bbfdm_micro_service.json b/docs/api/ubus/bbfdm_micro_service.json new file mode 100644 index 00000000..09faeee0 --- /dev/null +++ b/docs/api/ubus/bbfdm_micro_service.json @@ -0,0 +1,793 @@ +{ + "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" + ] + }, + "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" + ] + }, + "instance_mode_t": { + "type": "integer", + "default": 0, + "minimum": 0, + "maximum": 1 + }, + "trans_id_t": { + "description": "Required for CUD operation, it shall be same number as got from transaction->start", + "type": "integer", + "minimum": 1 + } + }, + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://dev.iopsys.eu/bbf/bbfdm/-/blob/devel/docs/api/ubus/bbfdm.md", + "type": "object", + "title": "bbf", + "object": "bbf", + "additionalProperties": false, + "properties": { + "schema": { + "title": "Get list of supported datamodel parameters", + "description": "Schema will have all the nodes/objects supported by libbbf", + "type": "object", + "required": [ + "output" + ], + "properties": { + "input": { + "type": "object", + "properties": { + "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": { + "proto": { + "$ref": "#/definitions/proto_t" + } + } + } + } + }, + "output": { + "type": "object", + "properties": { + "results": { + "type": "array", + "items": [ + { + "type": "object", + "properties": { + "path": { + "$ref": "#/definitions/schema_path_t" + }, + "data": { + "$ref": "#/definitions/boolean_t" + }, + "type": { + "$ref": "#/definitions/type_t" + }, + "fault": { + "$ref": "#/definitions/fault_t", + "Description": "Any discrepancy in input will result in fault. The type of fault can be identified by fault code" + }, + "fault_msg": { + "type": "string", + "Description": "Any discrepancy in input will result in fault. The type of fault can be identified by fault code" + }, + "input": { + "type": "array", + "items": [ + { + "type": "object", + "properties": { + "path": { + "$ref": "#/definitions/schema_path_t" + }, + "data": { + "$ref": "#/definitions/boolean_t" + }, + "type": { + "$ref": "#/definitions/type_t" + } + } + } + ] + }, + "output": { + "type": "array", + "items": [ + { + "type": "object", + "properties": { + "path": { + "$ref": "#/definitions/schema_path_t" + }, + "data": { + "$ref": "#/definitions/boolean_t" + }, + "type": { + "$ref": "#/definitions/type_t" + } + } + } + ] + } + }, + "required": [ + "path" + ] + } + ] + } + } + } + } + }, + "get": { + "title": "Get handler", + "description": "Query the datamodel object", + "type": "object", + "required": [ + "input", + "output" + ], + "properties": { + "input": { + "type": "object", + "required": [ + "path" + ], + "properties": { + "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": { + "format": { + "$ref": "#/definitions/format_t" + }, + "proto": { + "$ref": "#/definitions/proto_t" + }, + "instance_mode": { + "$ref": "#/definitions/instance_mode_t" + } + } + } + } + }, + "output": { + "type": "object", + "properties": { + "results": { + "type": "array", + "items": [ + { + "type": "object", + "properties": { + "path": { + "$ref": "#/definitions/path_t" + }, + "data": { + "type": "string" + }, + "type": { + "$ref": "#/definitions/type_t" + }, + "fault": { + "$ref": "#/definitions/fault_t", + "Description": "Any discrepancy in input will result in fault. The type of fault can be identified by fault code" + }, + "fault_msg": { + "type": "string", + "Description": "Any discrepancy in input will result in fault. The type of fault can be identified by fault code" + } + }, + "required": [ + "path" + ] + } + ] + } + } + } + } + }, + "instances": { + "title": "Instance query handler", + "description": "Get the instances of multi object", + "type": "object", + "required": [ + "input" + ], + "properties": { + "input": { + "type": "object", + "required": [ + "path" + ], + "properties": { + "path": { + "$ref": "#/definitions/query_path_t" + }, + "first_level": { + "type": "boolean", + "description": "gets only first level objects if true" + }, + "optional": { + "type": "object", + "properties": { + "proto": { + "$ref": "#/definitions/proto_t" + }, + "instance_mode": { + "$ref": "#/definitions/instance_mode_t" + } + } + } + } + }, + "output": { + "type": "object", + "properties": { + "results": { + "type": "array", + "items": [ + { + "type": "object", + "properties": { + "path": { + "$ref": "#/definitions/path_t" + }, + "fault": { + "$ref": "#/definitions/fault_t", + "Description": "Any discrepancy in input will result in fault. The type of fault can be identified by fault code" + }, + "fault_msg": { + "type": "string", + "Description": "Any discrepancy in input will result in fault. The type of fault can be identified by fault code" + } + }, + "required": [ + "path" + ] + } + ] + } + } + } + } + }, + "add": { + "title": "Add a new object instance", + "description": "Add a new object in multi instance object", + "type": "object", + "required": [ + "input", + "output" + ], + "properties": { + "input": { + "type": "object", + "required": [ + "path", + "optional" + ], + "properties": { + "path": { + "$ref": "#/definitions/path_t" + }, + "obj_path": { + "type": "object", + "properties": {} + }, + "optional": { + "type": "object", + "properties": { + "transaction_id": { + "$ref": "#/definitions/trans_id_t" + } + } + } + } + }, + "output": { + "type": "object", + "properties": { + "results": { + "type": "array", + "items": [ + { + "type": "object", + "properties": { + "path": { + "$ref": "#/definitions/path_t" + }, + "data": { + "type": "string" + }, + "fault": { + "$ref": "#/definitions/fault_t", + "Description": "Any discrepancy in input will result in fault. The type of fault can be identified by fault code" + }, + "fault_msg": { + "type": "string", + "Description": "Any discrepancy in input will result in fault. The type of fault can be identified by fault code" + } + }, + "required": [ + "path" + ] + } + ] + } + } + } + } + }, + "del": { + "title": "Delete object instance", + "description": "Delete a object instance from multi instance object", + "type": "object", + "required": [ + "input", + "output" + ], + "properties": { + "input": { + "type": "object", + "required": [ + "path", + "transaction_id" + ], + "properties": { + "path": { + "$ref": "#/definitions/path_t" + }, + "paths": { + "type": "array", + "uniqueItems": true, + "items": [ + { + "$ref": "#/definitions/query_path_t" + } + ] + }, + "optional": { + "type": "object", + "properties": { + "transaction_id": { + "$ref": "#/definitions/trans_id_t" + } + } + } + } + }, + "output": { + "type": "object", + "properties": { + "results": { + "type": "array", + "items": [ + { + "type": "object", + "properties": { + "path": { + "$ref": "#/definitions/path_t" + }, + "data": { + "type": "string" + }, + "fault": { + "$ref": "#/definitions/fault_t", + "Description": "Any discrepancy in input will result in fault. The type of fault can be identified by fault code" + }, + "fault_msg": { + "type": "string", + "Description": "Any discrepancy in input will result in fault. The type of fault can be identified by fault code" + } + }, + "required": [ + "parameter", + "type" + ] + } + ] + } + } + } + } + }, + "set": { + "title": "Set handler", + "description": "Set values of datamodel object element", + "type": "object", + "required": [ + "input", + "output" + ], + "properties": { + "input": { + "type": "object", + "required": [ + "path", + "value", + "optional" + ], + "properties": { + "path": { + "$ref": "#/definitions/query_path_t" + }, + "value": { + "description": "value of the object element provided in path, path should contains valid writable object element", + "type": "string", + "examples": [ + "{\"path\":\"Device.WiFi.SSID.1.SSID\", \"value\":\"test_ssid\"}", + "{\"path\":\"Device.WiFi.SSID.2.Enable\", \"value\":\"true\"}", + "{\"path\":\"Device.WiFi.SSID.1.Enable\", \"value\":\"0\"}" + ] + }, + "obj_path": { + "description": "To set multiple values at once, path should be relative to object elements", + "examples": [ + "{\"path\":\"Device.WiFi.SSID.1.\", \"obj_path\":{\"SSID\":\"test_ssid\",\"Name\":\"test_name\"}}", + "{\"path\":\"Device.WiFi.SSID.2.\", \"obj_path\":{\"SSID\":\"test_ssid\"}}" + ], + "type": "object", + "properties": {} + }, + "optional": { + "type": "object", + "properties": { + "proto": { + "$ref": "#/definitions/proto_t" + }, + "instance_mode": { + "$ref": "#/definitions/instance_mode_t" + }, + "transaction_id": { + "$ref": "#/definitions/trans_id_t" + } + } + } + } + }, + "output": { + "type": "object", + "properties": { + "results": { + "type": "array", + "items": [ + { + "type": "object", + "properties": { + "path": { + "$ref": "#/definitions/path_t" + }, + "data": { + "$ref": "#/definitions/boolean_t" + }, + "fault": { + "$ref": "#/definitions/fault_t", + "Description": "Any discrepancy in input will result in fault. The type of fault can be identified by fault code" + }, + "fault_msg": { + "type": "string", + "Description": "Any discrepancy in input will result in fault. The type of fault can be identified by fault code" + } + }, + "required": [ + "path" + ] + } + ] + } + } + } + } + }, + "operate": { + "title": "Operate handler", + "description": "Operate on object element provided in path", + "type": "object", + "required": [ + "input", + "output" + ], + "properties": { + "input": { + "type": "object", + "required": [ + "command" + ], + "properties": { + "command": { + "$ref": "#/definitions/operate_path_t" + }, + "command_key": { + "type": "string" + }, + "input": { + "description": "Input arguments for the operate command as defined in TR-181-2.13", + "examples": [ + "{\"path\":\"Device.IP.Diagnostics.IPPing\\(\\)\", \"input\":{\"Host\":\"iopsys.eu\"}}" + ], + "type": "object", + "properties": {} + }, + "optional": { + "type": "object", + "properties": { + "format": { + "$ref": "#/definitions/format_t" + }, + "proto": { + "$ref": "#/definitions/proto_t" + }, + "instance_mode": { + "$ref": "#/definitions/instance_mode_t" + } + } + } + } + }, + "output": { + "type": "object", + "properties": { + "results": { + "type": "array", + "items": [ + { + "type": "object", + "properties": { + "path": { + "$ref": "#/definitions/path_t" + }, + "data": { + "$ref": "#/definitions/boolean_t" + }, + "fault": { + "$ref": "#/definitions/fault_t", + "Description": "Any discrepancy in input will result in fault. The type of fault can be identified by fault code" + }, + "fault_msg": { + "type": "string", + "Description": "Any discrepancy in input will result in fault. The type of fault can be identified by fault code" + }, + "output": { + "type": "array", + "items": [ + { + "type": "object", + "properties": { + "path": { + "$ref": "#/definitions/path_t" + }, + "data": { + "$ref": "#/definitions/boolean_t" + }, + "type": { + "$ref": "#/definitions/type_t" + } + } + } + ] + } + }, + "required": [ + "path", + "data" + ] + } + ] + } + } + } + } + }, + "transaction": { + "title": "Start/commit/abort/status a transaction before set/add/del operations", + "type": "object", + "properties": { + "input": { + "type": "object", + "properties": { + "cmd": { + "$ref": "#/definitions/trans_type_t" + }, + "timeout": { + "type": "integer", + "description": "Timeout (in milliseconds) for the transaction, on timeout changes will be reverted", + "minimum":0 + }, + "restart_services": { + "description": "If yes, bbfdmd restart the service after CUD operation, else return list of updated uci to handler restart externally.", + "type": "boolean" + }, + "optional": { + "type": "object", + "properties": { + "transaction_id": { + "$ref": "#/definitions/trans_id_t" + } + } + } + }, + "required": [ + "cmd" + ] + }, + "output": { + "type": "object", + "properties": { + "status": { + "type": "boolean" + }, + "transaction_id": { + "type": "integer", + "minimum": 1 + }, + "error": { + "type": "string" + } + }, + "required": [ + "status" + ] + } + }, + "required": [ + "input", + "output" + ] + } + } +} diff --git a/docs/api/ubus/bbfdm_micro_service.md b/docs/api/ubus/bbfdm_micro_service.md new file mode 100644 index 00000000..ce5eead7 --- /dev/null +++ b/docs/api/ubus/bbfdm_micro_service.md @@ -0,0 +1,2066 @@ +# bbf Schema + +``` +https://dev.iopsys.eu/bbf/bbfdm/-/blob/devel/docs/api/ubus/bbfdm.md +``` + +| Custom Properties | Additional Properties | +| ----------------- | --------------------- | +| Forbidden | Forbidden | + +# 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) | +| [operate](#operate) | Method | bbf (this schema) | +| [schema](#schema) | Method | bbf (this schema) | +| [set](#set) | Method | bbf (this schema) | +| [transaction](#transaction) | Method | bbf (this schema) | + +## add + +### Add a new object instance + +Add a new object in multi instance object + +`add` + +- type: `Method` + +### add Type + +`object` with following properties: + +| Property | Type | Required | +| -------- | ------ | ------------ | +| `input` | object | **Required** | +| `output` | object | **Required** | + +#### input + +`input` + +- is **required** +- type: `object` + +##### input Type + +`object` with following properties: + +| Property | Type | Required | +| ---------- | ------ | ------------ | +| `obj_path` | object | Optional | +| `optional` | object | **Required** | +| `path` | string | **Required** | + +#### obj_path + +`obj_path` + +- is optional +- type: `object` + +##### obj_path Type + +`object` with following properties: + +| Property | Type | Required | +| -------- | ---- | -------- | +| None | None | None | + +#### optional + +`optional` + +- is **required** +- type: `object` + +##### optional Type + +`object` with following properties: + +| Property | Type | Required | +| ---------------- | ------- | -------- | +| `transaction_id` | integer | Optional | + +#### transaction_id + +Required for CUD operation, it shall be same number as got from transaction->start + +`transaction_id` + +- is optional +- type: reference + +##### transaction_id Type + +`integer` + +- minimum value: `1` + +#### path + +Complete object element path as per TR181 + +`path` + +- is **required** +- type: reference + +##### path Type + +`string` + +- minimum length: 6 characters +- maximum length: 1024 characters + +##### path Examples + +```json +Device. +``` + +```json +Device.DeviceInfo.Manufacturer +``` + +```json +Device.WiFi.SSID.1. +``` + +```json +Device.WiFi. +``` + +### Ubus CLI Example + +``` +ubus call bbf add {"path":"estanim Ut","optional":{"transaction_id":31269307},"obj_path":{}} +``` + +### JSONRPC Example + +```json +{ + "jsonrpc": "2.0", + "id": 0, + "method": "call", + "params": [ + "", + "bbf", + "add", + { "path": "estanim Ut", "optional": { "transaction_id": 31269307 }, "obj_path": {} } + ] +} +``` + +#### output + +`output` + +- is **required** +- type: `object` + +##### output Type + +`object` with following properties: + +| Property | Type | Required | +| --------- | ----- | -------- | +| `results` | array | Optional | + +#### results + +`results` + +- is optional +- type: `array` + +##### results Type + +Array type: `array` + +All items must be of the type: Unknown type ``. + +```json +{ + "type": "array", + "items": [ + { + "type": "object", + "properties": { + "path": { + "$ref": "#/definitions/path_t" + }, + "data": { + "type": "string" + }, + "fault": { + "$ref": "#/definitions/fault_t", + "Description": "Any discrepancy in input will result in fault. The type of fault can be identified by fault code" + }, + "fault_msg": { + "type": "string", + "Description": "Any discrepancy in input will result in fault. The type of fault can be identified by fault code" + } + }, + "required": ["path"] + } + ], + "simpletype": "`array`" +} +``` + +### Output Example + +```json +{ + "results": [ + { "path": "nulla voluptate eiusmod sit", "data": "ni", "fault": 7499, "fault_msg": "laboris pariatur tempor" } + ] +} +``` + +## del + +### Delete object instance + +Delete a object instance from multi instance object + +`del` + +- type: `Method` + +### del Type + +`object` with following properties: + +| Property | Type | Required | +| -------- | ------ | ------------ | +| `input` | object | **Required** | +| `output` | object | **Required** | + +#### input + +`input` + +- is **required** +- type: `object` + +##### input Type + +`object` with following properties: + +| Property | Type | Required | +| ---------- | ------ | ------------ | +| `optional` | object | Optional | +| `path` | string | **Required** | +| `paths` | array | Optional | + +#### optional + +`optional` + +- is optional +- type: `object` + +##### optional Type + +`object` with following properties: + +| Property | Type | Required | +| ---------------- | ------- | -------- | +| `transaction_id` | integer | Optional | + +#### transaction_id + +Required for CUD operation, it shall be same number as got from transaction->start + +`transaction_id` + +- is optional +- type: reference + +##### transaction_id Type + +`integer` + +- minimum value: `1` + +#### path + +Complete object element path as per TR181 + +`path` + +- is **required** +- type: reference + +##### path Type + +`string` + +- minimum length: 6 characters +- maximum length: 1024 characters + +##### path Examples + +```json +Device. +``` + +```json +Device.DeviceInfo.Manufacturer +``` + +```json +Device.WiFi.SSID.1. +``` + +```json +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 del {"path":"amet e","paths":["magna ani"],"optional":{"transaction_id":75019380}} +``` + +### JSONRPC Example + +```json +{ + "jsonrpc": "2.0", + "id": 0, + "method": "call", + "params": [ + "", + "bbf", + "del", + { "path": "amet e", "paths": ["magna ani"], "optional": { "transaction_id": 75019380 } } + ] +} +``` + +#### output + +`output` + +- is **required** +- type: `object` + +##### output Type + +`object` with following properties: + +| Property | Type | Required | +| --------- | ----- | -------- | +| `results` | array | Optional | + +#### results + +`results` + +- is optional +- type: `array` + +##### results Type + +Array type: `array` + +All items must be of the type: Unknown type ``. + +```json +{ + "type": "array", + "items": [ + { + "type": "object", + "properties": { + "path": { + "$ref": "#/definitions/path_t" + }, + "data": { + "type": "string" + }, + "fault": { + "$ref": "#/definitions/fault_t", + "Description": "Any discrepancy in input will result in fault. The type of fault can be identified by fault code" + }, + "fault_msg": { + "type": "string", + "Description": "Any discrepancy in input will result in fault. The type of fault can be identified by fault code" + } + }, + "required": ["parameter", "type"] + } + ], + "simpletype": "`array`" +} +``` + +### Output Example + +```json +{ + "results": [ + { "path": "qui ex officia", "data": "nostrud est do ex", "fault": 7045, "fault_msg": "sed sunt Lorem occaecat" } + ] +} +``` + +## get + +### Get handler + +Query the datamodel object + +`get` + +- type: `Method` + +### get Type + +`object` with following properties: + +| Property | Type | Required | +| -------- | ------ | ------------ | +| `input` | object | **Required** | +| `output` | object | **Required** | + +#### input + +`input` + +- is **required** +- type: `object` + +##### input Type + +`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` + +#### optional + +`optional` + +- is optional +- type: `object` + +##### optional Type + +`object` with following properties: + +| Property | Type | Required | Default | +| --------------- | ------- | -------- | ---------- | +| `format` | string | Optional | `"pretty"` | +| `instance_mode` | integer | Optional | `0` | +| `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](#get-known-values). + +##### format Known Values + +| Value | +| ------ | +| raw | +| pretty | + +#### instance_mode + +`instance_mode` + +- is optional +- type: reference +- default: `0` + +##### instance_mode Type + +`integer` + +- minimum value: `0` +- maximum value: `1` + +#### 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](#get-known-values). + +##### proto Known Values + +| Value | +| ----- | +| usp | +| cwmp | +| both | + +#### path + +DM object path with search queries + +`path` + +- is **required** +- type: reference + +##### path Type + +`string` + +- minimum length: 6 characters +- maximum length: 1024 characters + +##### path Examples + +```json +Device. +``` + +```json +Device.DeviceInfo.Manufacturer +``` + +```json +Device.WiFi.SSID.1.BSSID +``` + +```json +Device.WiFi.SSID.*.BSSID +``` + +```json +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 culpa","paths":["non voluptate"],"maxdepth":42643410,"optional":{"format":"pretty","proto":"both","instance_mode":0}} +``` + +### JSONRPC Example + +```json +{ + "jsonrpc": "2.0", + "id": 0, + "method": "call", + "params": [ + "", + "bbf", + "get", + { + "path": "occaecat culpa", + "paths": ["non voluptate"], + "maxdepth": 42643410, + "optional": { "format": "pretty", "proto": "both", "instance_mode": 0 } + } + ] +} +``` + +#### output + +`output` + +- is **required** +- type: `object` + +##### output Type + +`object` with following properties: + +| Property | Type | Required | +| --------- | ----- | -------- | +| `results` | array | Optional | + +#### results + +`results` + +- is optional +- type: `array` + +##### results Type + +Array type: `array` + +All items must be of the type: Unknown type ``. + +```json +{ + "type": "array", + "items": [ + { + "type": "object", + "properties": { + "path": { + "$ref": "#/definitions/path_t" + }, + "data": { + "type": "string" + }, + "type": { + "$ref": "#/definitions/type_t" + }, + "fault": { + "$ref": "#/definitions/fault_t", + "Description": "Any discrepancy in input will result in fault. The type of fault can be identified by fault code" + }, + "fault_msg": { + "type": "string", + "Description": "Any discrepancy in input will result in fault. The type of fault can be identified by fault code" + } + }, + "required": ["path"] + } + ], + "simpletype": "`array`" +} +``` + +### Output Example + +```json +{ "results": [{ "path": "veniam ", "data": "et", "type": "xsd:int", "fault": 7572, "fault_msg": "enim" }] } +``` + +## instances + +### Instance query handler + +Get the instances of multi object + +`instances` + +- type: `Method` + +### instances Type + +`object` with following properties: + +| Property | Type | Required | +| -------- | ------ | ------------ | +| `input` | object | **Required** | +| `output` | object | Optional | + +#### input + +`input` + +- is **required** +- type: `object` + +##### input Type + +`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` + +#### optional + +`optional` + +- is optional +- type: `object` + +##### optional Type + +`object` with following properties: + +| Property | Type | Required | Default | +| --------------- | ------- | -------- | -------- | +| `instance_mode` | integer | Optional | `0` | +| `proto` | string | Optional | `"both"` | + +#### instance_mode + +`instance_mode` + +- is optional +- type: reference +- default: `0` + +##### instance_mode Type + +`integer` + +- minimum value: `0` +- maximum value: `1` + +#### 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](#instances-known-values). + +##### proto Known Values + +| Value | +| ----- | +| usp | +| cwmp | +| both | + +#### path + +DM object path with search queries + +`path` + +- is **required** +- type: reference + +##### path Type + +`string` + +- minimum length: 6 characters +- maximum length: 1024 characters + +##### path Examples + +```json +Device. +``` + +```json +Device.DeviceInfo.Manufacturer +``` + +```json +Device.WiFi.SSID.1.BSSID +``` + +```json +Device.WiFi.SSID.*.BSSID +``` + +```json +Device.WiFi. +``` + +### Ubus CLI Example + +``` +ubus call bbf instances {"path":"fugiat anim Lorem reprehende","first_level":false,"optional":{"proto":"cwmp","instance_mode":0}} +``` + +### JSONRPC Example + +```json +{ + "jsonrpc": "2.0", + "id": 0, + "method": "call", + "params": [ + "", + "bbf", + "instances", + { + "path": "fugiat anim Lorem reprehende", + "first_level": false, + "optional": { "proto": "cwmp", "instance_mode": 0 } + } + ] +} +``` + +#### output + +`output` + +- is optional +- type: `object` + +##### output Type + +`object` with following properties: + +| Property | Type | Required | +| --------- | ----- | -------- | +| `results` | array | Optional | + +#### results + +`results` + +- is optional +- type: `array` + +##### results Type + +Array type: `array` + +All items must be of the type: Unknown type ``. + +```json +{ + "type": "array", + "items": [ + { + "type": "object", + "properties": { + "path": { + "$ref": "#/definitions/path_t" + }, + "fault": { + "$ref": "#/definitions/fault_t", + "Description": "Any discrepancy in input will result in fault. The type of fault can be identified by fault code" + }, + "fault_msg": { + "type": "string", + "Description": "Any discrepancy in input will result in fault. The type of fault can be identified by fault code" + } + }, + "required": ["path"] + } + ], + "simpletype": "`array`" +} +``` + +### Output Example + +```json +{ "results": [{ "path": "in ipsum proident Duis nulla", "fault": 8425, "fault_msg": "elit culpa" }] } +``` + +## operate + +### Operate handler + +Operate on object element provided in path + +`operate` + +- type: `Method` + +### operate Type + +`object` with following properties: + +| Property | Type | Required | +| -------- | ------ | ------------ | +| `input` | object | **Required** | +| `output` | object | **Required** | + +#### input + +`input` + +- is **required** +- type: `object` + +##### input Type + +`object` with following properties: + +| 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() +``` + +#### command_key + +`command_key` + +- is optional +- type: `string` + +##### command_key Type + +`string` + +#### input + +Input arguments for the operate command as defined in TR-181-2.13 + +`input` + +- is optional +- type: `object` + +##### input Type + +`object` with following properties: + +| Property | Type | Required | +| -------- | ---- | -------- | +| None | None | None | + +##### input Example + +```json +{ "path": "Device.IP.Diagnostics.IPPing()", "input": { "Host": "iopsys.eu" } } +``` + +#### optional + +`optional` + +- is optional +- type: `object` + +##### optional Type + +`object` with following properties: + +| Property | Type | Required | Default | +| --------------- | ------- | -------- | ---------- | +| `format` | string | Optional | `"pretty"` | +| `instance_mode` | integer | Optional | `0` | +| `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 | + +#### instance_mode + +`instance_mode` + +- is optional +- type: reference +- default: `0` + +##### instance_mode Type + +`integer` + +- minimum value: `0` +- maximum value: `1` + +#### 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](#operate-known-values). + +##### proto Known Values + +| Value | +| ----- | +| usp | +| cwmp | +| both | + +### Ubus CLI Example + +``` +ubus call bbf operate {"command":"exipsum cillum labore cupidatat minim","command_key":"ullamco nostrud sunt","input":{},"optional":{"format":"raw","proto":"both","instance_mode":1}} +``` + +### JSONRPC Example + +```json +{ + "jsonrpc": "2.0", + "id": 0, + "method": "call", + "params": [ + "", + "bbf", + "operate", + { + "command": "exipsum cillum labore cupidatat minim", + "command_key": "ullamco nostrud sunt", + "input": {}, + "optional": { "format": "raw", "proto": "both", "instance_mode": 1 } + } + ] +} +``` + +#### output + +`output` + +- is **required** +- type: `object` + +##### output Type + +`object` with following properties: + +| Property | Type | Required | +| --------- | ----- | -------- | +| `results` | array | Optional | + +#### results + +`results` + +- is optional +- type: `array` + +##### results Type + +Array type: `array` + +All items must be of the type: Unknown type ``. + +```json +{ + "type": "array", + "items": [ + { + "type": "object", + "properties": { + "path": { + "$ref": "#/definitions/path_t" + }, + "data": { + "$ref": "#/definitions/boolean_t" + }, + "fault": { + "$ref": "#/definitions/fault_t", + "Description": "Any discrepancy in input will result in fault. The type of fault can be identified by fault code" + }, + "fault_msg": { + "type": "string", + "Description": "Any discrepancy in input will result in fault. The type of fault can be identified by fault code" + }, + "output": { + "type": "array", + "items": [ + { + "type": "object", + "properties": { + "path": { + "$ref": "#/definitions/path_t" + }, + "data": { + "$ref": "#/definitions/boolean_t" + }, + "type": { + "$ref": "#/definitions/type_t" + } + } + } + ] + } + }, + "required": ["path", "data"] + } + ], + "simpletype": "`array`" +} +``` + +### Output Example + +```json +{ + "results": [ + { + "path": "deserunt cillum amet", + "data": "0", + "fault": 7140, + "fault_msg": "laborum", + "output": [{ "path": "proident", "data": "1", "type": "xsd:boolean" }] + } + ] +} +``` + +## schema + +### Get list of supported datamodel parameters + +Schema will have all the nodes/objects supported by libbbf + +`schema` + +- type: `Method` + +### schema Type + +`object` with following properties: + +| Property | Type | Required | +| -------- | ------ | ------------ | +| `input` | object | Optional | +| `output` | object | **Required** | + +#### input + +`input` + +- is optional +- type: `object` + +##### input Type + +`object` with following properties: + +| 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 + +gets only first level objects if true + +`first_level` + +- is optional +- type: `boolean` + +##### first_level Type + +`boolean` + +#### optional + +`optional` + +- is optional +- type: `object` + +##### optional Type + +`object` with following properties: + +| Property | Type | Required | Default | +| -------- | ------ | -------- | -------- | +| `proto` | string | Optional | `"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](#schema-known-values). + +##### proto Known Values + +| Value | +| ----- | +| usp | +| 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 + +`path` + +- is optional +- type: reference + +##### path Type + +`string` + +- minimum length: 6 characters +- maximum length: 1024 characters + +##### path Examples + +```json +Device. +``` + +```json +Device.DeviceInfo.Manufacturer +``` + +```json +Device.WiFi.SSID.1.BSSID +``` + +```json +Device.WiFi.SSID.*.BSSID +``` + +```json +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":"magna cillum consequat","paths":["nisi nulla ullamco"],"first_level":false,"commands":false,"events":true,"params":false,"optional":{"proto":"both"}} +``` + +### JSONRPC Example + +```json +{ + "jsonrpc": "2.0", + "id": 0, + "method": "call", + "params": [ + "", + "bbf", + "schema", + { + "path": "magna cillum consequat", + "paths": ["nisi nulla ullamco"], + "first_level": false, + "commands": false, + "events": true, + "params": false, + "optional": { "proto": "both" } + } + ] +} +``` + +#### output + +`output` + +- is **required** +- type: `object` + +##### output Type + +`object` with following properties: + +| Property | Type | Required | +| --------- | ----- | -------- | +| `results` | array | Optional | + +#### results + +`results` + +- is optional +- type: `array` + +##### results Type + +Array type: `array` + +All items must be of the type: Unknown type ``. + +```json +{ + "type": "array", + "items": [ + { + "type": "object", + "properties": { + "path": { + "$ref": "#/definitions/schema_path_t" + }, + "data": { + "$ref": "#/definitions/boolean_t" + }, + "type": { + "$ref": "#/definitions/type_t" + }, + "fault": { + "$ref": "#/definitions/fault_t", + "Description": "Any discrepancy in input will result in fault. The type of fault can be identified by fault code" + }, + "fault_msg": { + "type": "string", + "Description": "Any discrepancy in input will result in fault. The type of fault can be identified by fault code" + }, + "input": { + "type": "array", + "items": [ + { + "type": "object", + "properties": { + "path": { + "$ref": "#/definitions/schema_path_t" + }, + "data": { + "$ref": "#/definitions/boolean_t" + }, + "type": { + "$ref": "#/definitions/type_t" + } + } + } + ] + }, + "output": { + "type": "array", + "items": [ + { + "type": "object", + "properties": { + "path": { + "$ref": "#/definitions/schema_path_t" + }, + "data": { + "$ref": "#/definitions/boolean_t" + }, + "type": { + "$ref": "#/definitions/type_t" + } + } + } + ] + } + }, + "required": ["path"] + } + ], + "simpletype": "`array`" +} +``` + +### Output Example + +```json +{ + "results": [ + { + "path": "Duis in dolore", + "data": "0", + "type": "xsd:dateTime", + "fault": 7341, + "fault_msg": "", + "input": [{ "path": "veniam officia consectetur aute", "data": "0", "type": "xsd:dateTime" }], + "output": [{ "path": "velit laboris Lorem proident officia", "data": "1", "type": "xsd:unsignedLong" }] + } + ] +} +``` + +## set + +### Set handler + +Set values of datamodel object element + +`set` + +- type: `Method` + +### set Type + +`object` with following properties: + +| Property | Type | Required | +| -------- | ------ | ------------ | +| `input` | object | **Required** | +| `output` | object | **Required** | + +#### input + +`input` + +- is **required** +- type: `object` + +##### input Type + +`object` with following properties: + +| Property | Type | Required | +| ---------- | ------ | ------------ | +| `obj_path` | object | Optional | +| `optional` | object | **Required** | +| `path` | string | **Required** | +| `value` | string | **Required** | + +#### obj_path + +To set multiple values at once, path should be relative to object elements + +`obj_path` + +- is optional +- type: `object` + +##### obj_path Type + +`object` with following properties: + +| Property | Type | Required | +| -------- | ---- | -------- | +| None | None | None | + +##### obj_path Examples + +```json +{ "path": "Device.WiFi.SSID.1.", "obj_path": { "SSID": "test_ssid", "Name": "test_name" } } +``` + +```json +{ "path": "Device.WiFi.SSID.2.", "obj_path": { "SSID": "test_ssid" } } +``` + +#### optional + +`optional` + +- is **required** +- type: `object` + +##### optional Type + +`object` with following properties: + +| Property | Type | Required | Default | +| ---------------- | ------- | -------- | -------- | +| `instance_mode` | integer | Optional | `0` | +| `proto` | string | Optional | `"both"` | +| `transaction_id` | integer | Optional | | + +#### instance_mode + +`instance_mode` + +- is optional +- type: reference +- default: `0` + +##### instance_mode Type + +`integer` + +- minimum value: `0` +- maximum value: `1` + +#### 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](#set-known-values). + +##### proto Known Values + +| Value | +| ----- | +| usp | +| cwmp | +| both | + +#### transaction_id + +Required for CUD operation, it shall be same number as got from transaction->start + +`transaction_id` + +- is optional +- type: reference + +##### transaction_id Type + +`integer` + +- minimum value: `1` + +#### path + +DM object path with search queries + +`path` + +- is **required** +- type: reference + +##### path Type + +`string` + +- minimum length: 6 characters +- maximum length: 1024 characters + +##### path Examples + +```json +Device. +``` + +```json +Device.DeviceInfo.Manufacturer +``` + +```json +Device.WiFi.SSID.1.BSSID +``` + +```json +Device.WiFi.SSID.*.BSSID +``` + +```json +Device.WiFi. +``` + +#### value + +value of the object element provided in path, path should contains valid writable object element + +`value` + +- is **required** +- type: `string` + +##### value Type + +`string` + +##### value Examples + +```json +{ "path": "Device.WiFi.SSID.1.SSID", "value": "test_ssid" } +``` + +```json +{ "path": "Device.WiFi.SSID.2.Enable", "value": "true" } +``` + +```json +{ "path": "Device.WiFi.SSID.1.Enable", "value": "0" } +``` + +### Ubus CLI Example + +``` +ubus call bbf set {"path":"qui ullamco non","value":"ut aliquip anim ex","optional":{"proto":"cwmp","instance_mode":0,"transaction_id":62652682},"obj_path":{}} +``` + +### JSONRPC Example + +```json +{ + "jsonrpc": "2.0", + "id": 0, + "method": "call", + "params": [ + "", + "bbf", + "set", + { + "path": "qui ullamco non", + "value": "ut aliquip anim ex", + "optional": { "proto": "cwmp", "instance_mode": 0, "transaction_id": 62652682 }, + "obj_path": {} + } + ] +} +``` + +#### output + +`output` + +- is **required** +- type: `object` + +##### output Type + +`object` with following properties: + +| Property | Type | Required | +| --------- | ----- | -------- | +| `results` | array | Optional | + +#### results + +`results` + +- is optional +- type: `array` + +##### results Type + +Array type: `array` + +All items must be of the type: Unknown type ``. + +```json +{ + "type": "array", + "items": [ + { + "type": "object", + "properties": { + "path": { + "$ref": "#/definitions/path_t" + }, + "data": { + "$ref": "#/definitions/boolean_t" + }, + "fault": { + "$ref": "#/definitions/fault_t", + "Description": "Any discrepancy in input will result in fault. The type of fault can be identified by fault code" + }, + "fault_msg": { + "type": "string", + "Description": "Any discrepancy in input will result in fault. The type of fault can be identified by fault code" + } + }, + "required": ["path"] + } + ], + "simpletype": "`array`" +} +``` + +### Output Example + +```json +{ "results": [{ "path": "labore et amet", "data": "0", "fault": 7959, "fault_msg": "dolor sunt" }] } +``` + +## transaction + +### Start/commit/abort/status a transaction before set/add/del operations + +`transaction` + +- type: `Method` + +### transaction Type + +`object` with following properties: + +| Property | Type | Required | +| -------- | ------ | ------------ | +| `input` | object | **Required** | +| `output` | object | **Required** | + +#### input + +`input` + +- is **required** +- type: `object` + +##### input Type + +`object` with following properties: + +| Property | Type | Required | +| ------------------ | ------- | ------------ | +| `cmd` | string | **Required** | +| `optional` | object | Optional | +| `restart_services` | boolean | Optional | +| `timeout` | integer | Optional | + +#### cmd + +`cmd` + +- is **required** +- type: reference + +##### cmd Type + +`string` + +The value of this property **must** be equal to one of the [known values below](#transaction-known-values). + +##### cmd Known Values + +| Value | +| ------ | +| start | +| commit | +| abort | +| status | + +#### optional + +`optional` + +- is optional +- type: `object` + +##### optional Type + +`object` with following properties: + +| Property | Type | Required | +| ---------------- | ------- | -------- | +| `transaction_id` | integer | Optional | + +#### transaction_id + +Required for CUD operation, it shall be same number as got from transaction->start + +`transaction_id` + +- is optional +- type: reference + +##### transaction_id Type + +`integer` + +- minimum value: `1` + +#### restart_services + +If yes, bbfdmd restart the service after CUD operation, else return list of updated uci to handler restart externally. + +`restart_services` + +- is optional +- type: `boolean` + +##### restart_services Type + +`boolean` + +#### timeout + +Timeout (in milliseconds) for the transaction, on timeout changes will be reverted + +`timeout` + +- is optional +- type: `integer` + +##### timeout Type + +`integer` + +- minimum value: `0` + +### Ubus CLI Example + +``` +ubus call bbf transaction {"cmd":"start","timeout":81531371,"restart_services":false,"optional":{"transaction_id":25600713}} +``` + +### JSONRPC Example + +```json +{ + "jsonrpc": "2.0", + "id": 0, + "method": "call", + "params": [ + "", + "bbf", + "transaction", + { "cmd": "start", "timeout": 81531371, "restart_services": false, "optional": { "transaction_id": 25600713 } } + ] +} +``` + +#### output + +`output` + +- is **required** +- type: `object` + +##### output Type + +`object` with following properties: + +| Property | Type | Required | +| ---------------- | ------- | ------------ | +| `error` | string | Optional | +| `status` | boolean | **Required** | +| `transaction_id` | integer | Optional | + +#### error + +`error` + +- is optional +- type: `string` + +##### error Type + +`string` + +#### status + +`status` + +- is **required** +- type: `boolean` + +##### status Type + +`boolean` + +#### transaction_id + +`transaction_id` + +- is optional +- type: `integer` + +##### transaction_id Type + +`integer` + +- minimum value: `1` + +### Output Example + +```json +{ "status": false, "transaction_id": 44817555, "error": "labore id laborum mollit" } +``` diff --git a/schemas/uci/bbfdm.json b/docs/api/uci/bbfdm.json similarity index 71% rename from schemas/uci/bbfdm.json rename to docs/api/uci/bbfdm.json index 6f43f2b1..28a13f13 100644 --- a/schemas/uci/bbfdm.json +++ b/docs/api/uci/bbfdm.json @@ -5,6 +5,13 @@ "description": "BBFDM daemon Settings", "multi": false, "options": [ + { + "name": "enable", + "type": "boolean", + "required": "no", + "default": "1", + "description": "Enables bbfdmd" + }, { "name": "debug", "type": "boolean", @@ -40,13 +47,6 @@ "default": "2", "description": "This parameter configures when subprocess can be used for get operation. Level here denotes the Datamodel object depth up-to which subprocess will be used to collect the get data. For example, if this is configured to 1, then only get for 'Device.' shall be called within the subprocess. If configured as level 2, then all the get with up-to depth 2 like 'Device.WiFi.', 'Device.IP.' shall be called in subprocess." }, - { - "name": "bbf_caching_time", - "type": "integer", - "required": "no", - "default": "0", - "description": "Max caching time in seconds for ubus output used in datamodel parameters. If not configured, output shall be cleared end the end of call." - }, { "name": "refresh_time", "type": "integer", @@ -55,6 +55,34 @@ "description": "The time period in seconds after which bbfdmd will refresh the datamodel instances in a periodic manner. If configured to '0' then instance updater will be disabled. If not configured at all then after every 5 seconds datamodel instances will be refreshed." } ] + }, + { + "section": "micro_services", + "description": "Datamodel micro-service", + "multi": false, + "options": [ + { + "name": "enable", + "type": "boolean", + "required": "no", + "default": "1", + "description": "Enables bbfdmd" + }, + { + "name": "enable_core", + "type": "boolean", + "required": "no", + "default": "0", + "description": "Sets core flag in procd for datamodel microservices" + }, + { + "name": "enable_respawn", + "type": "boolean", + "required": "no", + "default": "0", + "description": "Enable respawning of datamodel micro-service process" + } + ] } ] } diff --git a/docs/guide/How_to_extend_datamodel_with_C_Code.md b/docs/guide/How_to_extend_datamodel_with_C_Code.md new file mode 100644 index 00000000..05e2cf6b --- /dev/null +++ b/docs/guide/How_to_extend_datamodel_with_C_Code.md @@ -0,0 +1,281 @@ +# How to Write a datamodel definition using C code + +Datamodel definition can be added manually by defining the whole tree node-by-node or structure-by-structure, or can be semi-automated by using a `bbfdm` tool, which generates template C source code with all the structure definitions and dummy get/set/add/delete handlers. + +## Generate datamodel source code with dummy definition using tool + +```bash +./tools/convert_dm_json_to_c.py --help +Usage: ./tools/convert_dm_json_to_c.py [Object path] +Examples: + - ./tools/convert_dm_json_to_c.py + ==> Generate the C code of full data model in datamodel/ folder + - ./tools/convert_dm_json_to_c.py Device.DeviceInfo. + ==> Generate the C code of Device.DeviceInfo object in datamodel/ folder + - ./tools/convert_dm_json_to_c.py Device.Services.VoiceService.{i}.DECT.Base.{i}. + ==> Generate the C code for a specific multi-instance object in datamodel/ folder +``` + +After running the tool, datamodel shall be gets generated in datamodel directory with dummy handlers with '//TODO' marker, to complete the definition, developer need to update the logic in dummy function pointers. + +To know more about different type of function pointers, check below section. + +## Write datamodel source code manually + +To write a datamodel definition manually, one has to add the Root definition along with object and leaves. + +### Root definition + +As per TR181, the root of the tree is 'Device.', which can be defined by using below named structure 'tDynamicObj' + +```bash +DM_MAP_OBJ tDynamicObj[] = { +{"Device.", tDeviceObj, tDeviceParams}, +{0} +}; +``` + +The “tDynamicObj” table contains entries of **DM_MAP_OBJ** structure, which contains three arguments: + +| Argument | Description | +| ---------------- | ------------------------------------------------------------------------------------------------------------- | +| `parentobj` | A string of the parent object name. Example “Device.IP.Diagnostics.”, “Device.DeviceInfo”, “Device.WiFi.Radio.” | +| `nextobject` | Pointer to a **DMOBJ** array which contains a list of the child objects | +| `parameter` | Pointer to a **DMLEAF** array which contains a list of the child parameters | + + +> Note: This symbol needs to be defined once per module globally, and has the root definition for that module's datamodels + +Datamodel can be divided in two parts, +1. Intermediate nodes or objects (defined with DMOBJ) +2. End nodes or leaf parameters (defined with DMLEAF) + +### Object definition (DMOBJ) + +Each object in the **DMOBJ** table contains the following arguments: + +| Argument | Description | +| ------------------- | ---------------------------------------------------------------------------------------------- | +| `OBJ` | A string of the object name. Example “Bridging”, “IP”, “DeviceInfo”, “WiFi” | +| `permission` | The permission of the object. Could be **&DMREAD** or **&DMWRITE**. If it's `&DMWRITE` then we can add/delete instances of this object | +| `addobj` | The function to add new instance under this object. This function will be triggered when the ACS/Controller call AddObject of this object | +| `delobj` | The function to delete instance under this object. This function will be triggered when the ACS/Controller call DeleteObject of an instance of this object | +| `checkdep` | A string of the object dependency, it can be a file("file:/etc/config/network") or an ubus object,method("ubus:network.interface->status"). If it's `NULL` then the object has always appeared in the tree | +| `browseinstobj` | This function allow to browse all instances under this object | +| `nextdynamicobj` | Pointer to the next of **DMOBJ** which contains a list of the child objects using json files, shared libraries and vendor extension | +| `dynamicleaf` | Pointer to the next of **DMLEAF** which contains a list of the child parameters using json files, shared libraries and vendor extension | +| `nextobj` | Pointer to a **DMOBJ** array which contains a list of the child objects | +| `leaf` | Pointer to a **DMLEAF** array which contains a list of the child parameters | +| `linker` | This argument is deprecated and should be `NULL` | +| `bbfdm_type` | The bbfdm type of the object. Could be **BBFDM_CWMP**, **BBFDM_USP**, **BBFDM_BOTH** or **BBFDM_NONE**.If it's **BBFDM_BOTH** then we can see this object in all protocols (CWMP, USP,...) | +| `uniqueKeys` | This argument is deprecated and should be `NULL` | + + +example: +```bash +/* *** Device. *** */ +DMOBJ tDeviceObj[] = { +/* OBJ, permission, addobj, delobj, checkdep, browseinstobj, nextdynamicobj, dynamicleaf, nextobj, leaf, linker, bbfdm_type*/ +{"DeviceInfo", &DMREAD, NULL, NULL, NULL, NULL, NULL, NULL, tDeviceInfoObj, tDeviceInfoParams, NULL, BBFDM_BOTH, NULL}, +{0} +}; +``` + +Datamodel objects can be of two types + +- Single instance object (Path which has a '.' prefix) +- Multi-instance objects (Path with has '.{i}' prefix) + +Multi-instance objects means, there could be one or more such nodes available, it can be viewed as a group of things which also has a close resemblance with 'uci sections'. In datamodel definitions, this mostly depends on runtime data, and to define such object, one has to define a `browseinstobj` function pointer to dynamically gather data and create instances at the runtime. + +#### Browse definition + +The browse function allow to go over all instances of the current object and link them to the data model tree. So, it need to retrieve the instance number for the current instance and then create a link between current instance and existing defined tree. + +To retrieve the instance, below APIs can be used + +- `handle_instance`: allow to retrieve/attribute the instances number/alias from uci config sections depending of the request and the instance mode. +- `handle_instance_without_section`: allow to attribute the instances number/alias with constant values. + +To link the current instance with the datamodel definition +- DM_LINK_INST_OBJ: This API needs to be called for each instance, this API also has a structure called `dm_data` which can be used to pass-on the data from current node to child objects. + +> Note1: It is **mandatory** to use the generic structure `(struct dm_data *)` to pass the data to child objects/params. + +> Note2: the browse function is only required for multi-instances objects. + +### Leaf definition + +Each leaf in the **DMLEAF** table can be a **Parameter**, **Command** or **Event**. + + +#### 1.Parameter definition + +| Argument | Description | +| ------------------- | -------------------------------------------------------------------------------------------------- | +| `PARAM` | A string of the parameter name. Example “Enable”, “Status”, “Name” | +| `permission` | The permission of the parameter. Could be **&DMREAD** or **&DMWRITE**.If it's `&DMWRITE` then we can set a value for this parameter | +| `type` | Type of the parameter: **DM_STRING**, **DM_BOOL**, **DM_UNINT**,... | +| `getvalue` | The function which return the value of this parameter | +| `setvalue` | The function which set the value of this parameter | +| `bbfdm_type` | The bbfdm type of the parameter. Could be **BBFDM_CWMP**, **BBFDM_USP**, **BBFDM_BOTH** or **BBFDM_NONE**.If it's **BBFDM_BOTH** then we can see this parameter in all protocols (CWMP, USP,...) | +| `dm_falgs` | An enumeration value used to specify the displayed parameter value. Could be **DM_FLAG_REFERENCE**, **DM_FLAG_UNIQUE**, **DM_FLAG_LINKER** or **DM_FLAG_SECURE**. | + +#### 2.Command definition + +| Argument | Description | +| ------------------- | -------------------------------------------------------------------------------------------------- | +| `PARAM` | A string of the command name. Example “IPPing()”, “DownloadDiagnostics()”, “Renew()” | +| `permission` | The permission of the command. Could be **&DMASYNC** or **&DMSYNC**. | +| `type` | Type of the command, It should be **DMT_COMMAND** | +| `getvalue` | The function which return the input, output arguments of the command | +| `setvalue` | The function which call the operation of the command | +| `bbfdm_type` | The bbfdm type of the command. It should be **BBFDM_USP** as long as operate commands are only defined in USP protocol. | + + +#### 3.Event definition + +| Argument | Description | +| ------------------- | -------------------------------------------------------------------------------------------------- | +| `PARAM` | A string of the event name. Example “Boot!”, “Push!”, “Periodic!” | +| `permission` | The permission of the event. It should be **DMREAD** | +| `type` | Type of the event, It should be **DMT_EVENT** | +| `getvalue` | The function which return the parameter arguments of the event | +| `setvalue` | The function which call the operation of the event | +| `bbfdm_type` | The bbfdm type of the event. It should be **BBFDM_USP** as long as events are only defined in USP protocol. | + +##### How events works + +A datamodel event can be sent from external source (like: hotplug script) or it can be auto-generated based on system events. `bbfdmd` provides a methods to trigger datamodel event from ubus event. + +Upon starting `bbfdmd`, it calls `bbf_entry_method` API with `BBF_SCHEMA` method to retrieve all events supported by Data Model. Subsequently, it attempts to register an event handler for each event by using the event name argument defined in each event leaf and then listens for that event name. + +When the ubus event triggered in the system, `bbfdmd` calls `bbf_entry_method` API with `BBF_EVENT` method to perform the event operation. And finally, it sends `bbfdm.event` ubus event with the required input information obtained from the returned event operation. + +Example: + +Below is an example of `Device.WiFi.DataElements.AssociationEvent.Associated!` event implementation: +```bash +static event_args wifidataelementsassociationevent_associated_args = { + .name = "wifi.dataelements.Associated", + .param = (const char *[]) { + "type", + "version", + "protocols", + "BSSID", + "MACAddress", + "StatusCode", + "HTCapabilities", + "VHTCapabilities", + "HECapabilities", + "TimeStamp", + NULL + } +}; + +static int get_event_args_WiFiDataElementsAssociationEvent_Associated(char *refparam, struct dmctx *ctx, void *data, char *instance, char **value) +{ + *value = (char *)&wifidataelementsassociationevent_associated_args; + return 0; +} + +static int event_WiFiDataElementsAssociationEvent_Associated(char *refparam, struct dmctx *ctx, void *data, char *instance, char *value, int action) +{ + switch (action) { + case EVENT_CHECK: + // Nothing to check + break; + case EVENT_RUN: + char *event_time = dmjson_get_value((json_object *)value, 1, "eventTime"); + char *bssid = dmjson_get_value((json_object *)value, 3, "wfa-dataelements:AssociationEvent.AssocData", "DisassocData", "BSSID"); + char *mac_addr = dmjson_get_value((json_object *)value, 3, "wfa-dataelements:AssociationEvent.AssocData", "DisassocData", "MACAddress"); + + add_list_parameter(ctx, dmstrdup("TimeStamp"), dmstrdup(event_time), DMT_TYPE[DMT_STRING], NULL); + add_list_parameter(ctx, dmstrdup("BSSID"), dmstrdup(bssid), DMT_TYPE[DMT_STRING], NULL); + add_list_parameter(ctx, dmstrdup("MACAddress"), dmstrdup(mac_addr), DMT_TYPE[DMT_STRING], NULL); + break; + } + + return 0; +} + +DMLEAF tWiFiDataElementsAssociationEventParams[] = { +/* PARAM, permission, type, getvalue, setvalue, bbfdm_type*/ +{"Associated!", &DMREAD, DMT_EVENT, get_event_args_WiFiDataElementsAssociationEvent_Associated, event_WiFiDataElementsAssociationEvent_Associated, BBFDM_USP}, +{0} +}; +``` + +More leaf Example(s): + +```bash +DMLEAF tDeviceParams[] = { +/* PARAM, permission, type, getvalue, setvalue, bbfdm_type, version*/ +{"RootDataModelVersion", &DMREAD, DMT_STRING, get_Device_RootDataModelVersion, NULL, BBFDM_BOTH}, +{"Reboot()", &DMSYNC, DMT_COMMAND, NULL, operate_Device_Reboot, BBFDM_USP}, +{"Boot!", &DMREAD, DMT_EVENT, NULL, NULL, BBFDM_USP}, +{0} +}; +``` + +#### Alias handling +In general datamodel parameters with multi-instance objects has a parameter named as '.Alias' to uniquely identify the instance. Below APIs can be used to get/set Aliases, provided browseinstobj has dmmap definition in dm_data. + +- Alias get handler (`bbf_get_alias`) +- Alias set handler (`bbf_set_alias`) + +```bash +int bbf_get_alias(struct dmctx *ctx, struct uci_section *s, char *option_name, char *instance, char **value) +``` + +Input(s): + +| Input | Description | +| ------ | ------------ | +| ctx | bbf context | +| s | Pointer to dmmap uci section from where will get Alias value | +| option_name| dmmap uci option name for alias value | +| instance | instance value | +| value | pointer to where the value will be stored | + +```bash +int bbf_set_alias(struct dmctx *ctx, struct uci_section *s, char *option_name, char *instance, char *value); +``` + +Input(s): + +| Input | Description | +| ------ | ------------ | +| ctx | bbf context | +| s | Pointer to dmmap uci section to where will save Alias value | +| option_name | dmmap uci option name to store the alias value | +| instance | instance value | +| value | the value to be set | + +Example: +```bash +static int get_WiFiEndPoint_Alias(char *refparam, struct dmctx *ctx, void *data, char *instance, char **value) +{ + return bbf_get_alias(ctx, ((struct dm_data *)data)->dmmap_section, "endpointalias", instance, value); +} + +static int set_WiFiEndPoint_Alias(char *refparam, struct dmctx *ctx, void *data, char *instance, char *value, int action) +{ + return bbf_set_alias(ctx, ((struct dm_data *)data)->dmmap_section, "endpointalias", instance, value); +} +``` + +#### NumberOfEntries parameter handling + +Each multi-instance object has a related LEAF entry to denote the number of instances present for that object, Since multi-instance object already has a browse function which got the runtime logic to loop through the instances, `libbbfdm-api` provides another API `get_number_of_entries` to get the number of entries. + +Example: + +```bash +static int get_Device_InterfaceStackNumberOfEntries(char *refparam, struct dmctx *ctx, void *data, char *instance, char **value) +{ + int cnt = get_number_of_entries(ctx, data, instance, browseInterfaceStackInst); + dmasprintf(value, "%d", cnt); + return 0; +} +``` diff --git a/docs/guide/libbbfdm-api_json_plugin_v1.md b/docs/guide/How_to_extend_datamodel_with_JSON.md similarity index 51% rename from docs/guide/libbbfdm-api_json_plugin_v1.md rename to docs/guide/How_to_extend_datamodel_with_JSON.md index e46ef90f..93e1fd43 100644 --- a/docs/guide/libbbfdm-api_json_plugin_v1.md +++ b/docs/guide/How_to_extend_datamodel_with_JSON.md @@ -1,13 +1,14 @@ -# How to extend Datamodel parameters using Json plugins +# How to extend Datamodel parameters using Json -It is often required to extend datamodel parameters of the device, extending the datamodel parameters using json plugin is the simplest way for the same. +`bbfdm` provides tools to convert Broadband-forum's xml datamodel definition for cwmp and usp to a combined JSON file. -To extend the datamodel using json plugin, its required to be defined it, as it is defined in `datamodel.json` file and then place that json in '/etc/bbfdm/json/' directory of device. +JSON definition of datamodel with latest release available in [datamodel.json](../../libbbfdm/dmtree/json/datamodel.json) + +Now, a partial node from this file can be used to create a JSON datamodel definition, provided user adds a mapping to all LEAF parameters and multi-instance object. -It is often the case, that the supported mapping might not handle all the scenarios, and required some structural changes to fulfill the new requirements, to make these plugins backward compatible with the older mappings some kind of check was required, which is can be solved with having a "version" field in the plugin, which describes the list of supported mappings with that specific version. This can be added as below: ```json { - "json_plugin_version": 1, + "json_plugin_version": 2, "Device.": { "type": "object", "protocols": [ @@ -65,11 +66,490 @@ It is often the case, that the supported mapping might not handle all the scenar } } ``` -> Note: If the `json_plugin_version` is omitted in the json then it means, it is having legacy mapping and considered as `json_plugin_version` 0. + +> Note1: `json_plugin_version` is **mandatory** in json datamodel definition. + +> Note2: It is advised to use `json_plugin_version` 2 for datamodel definition, usages version 0 and 1 are deprecated. + +## JSON Plugin Version 2 + +Earlier versions of the json_plugins where treated as separate tree, so there where no sharing of data between main tree and JSON plugin, also it was not possible to overwrite/exclude a datamodel entry from core using JSON file. + +JSON Plugin Version 2 introduces enhancements to the previous versions by providing increased flexibility in extending, overwriting, and excluding objects/parameters/commands/events from the core data model. + +### How It Works + +To illustrate how the new features work, let's consider the following example JSON Plugin: + +```json +{ + "json_plugin_version": 2, + "Device.WiFi.AccessPoint.{i}.Security.": { + "type": "object", + "protocols": [ + "cwmp", + "usp" + ], + "access": false, + "array": false, + "{BBF_VENDOR_PREFIX}KeyPassphrase": { + "type": "string", + "read": true, + "write": true, + "protocols": [ + "cwmp", + "usp" + ], + "datatype": "string", + "mapping": [ + { + "data": "@Parent", + "type": "uci_sec", + "key": "key" + } + ] + }, + "WEPKey": { + "type": "string", + "read": true, + "write": true, + "protocols": [ + "cwmp", + "usp" + ], + "datatype": "string", + "mapping": [ + { + "data": "@Parent", + "type": "uci_sec", + "key": "wek_key" + } + ] + }, + "SAEPassphrase": { + "type": "string", + "read": true, + "write": false, + "protocols": [ + "none" + ] + } + } +} +``` + +The JSON Plugin V2 operates by parsing the JSON file. Then it checks the parent top object, which in this example is `Device.WiFi.AccessPoint.{i}.Security`. + +- If this object exists in the core data model, the plugin proceeds to examine the next each subsequent level to determine the necessary action for each JSON object. + - If the object does not exist in the core data model, it is extended. + - If the object exists, it is either overwritten or excluded, depending on the defined protocols. If the protocols array is defined as 'none', the object is excluded. + - If the parent top object does not exist in the core data model, the plugin follows the old behavior defined in JSON Plugin V0 and V1, which is extending the core data model. + +Examples + + - Device.WiFi.AccessPoint.{i}.Security.X_IOPSYS_EU_KeyPassphrase: This parameter will be extended to the core data model since it does not exist. + - Device.WiFi.AccessPoint.{i}.Security.WEPKey: This parameter will be overwritten in the core data model since it already exists. + - Device.WiFi.AccessPoint.{i}.Security.SAEPassphrase: This parameter will be excluded from the core data model since it exists, but the new protocol defined is `none`. + +More example(s): +- [Extend](../../test/vendor_test/test_extend.json) +- [Overwrite](../../test/vendor_test/test_overwrite.json), and +- [Exclude](../../test/vendor_test/test_exclude.json) + +### Important Notes + +> Note: When extending a multiple-instance object, align the passed data from the browse function to children (LEAF) by keeping it `(struct uci_section *)data` pointer in case of the `type` is `uci_sec` or `(json_object *)data` pointer in case of the `type` is `json`. + +> Note: The mapping format used by JSON Plugin V2 follows the format of version 1. Ensure that all mappings are aligned with JSON Plugin V1 specifications. + +> Note4: Additional examples for each feature can be found in the following links: + + +### Features Supported with JSON Plugin V2 + + - Allow extending the core tree with simple mappings based on the data passed from the parent object. + - Allow overwriting an existing object, parameter, command, or event from the core tree. + - Allow excluding an existing object, parameter, command, or event from the core tree. + +#### Some examples on JSON Definition + +**1. Object without instance:** + +```bash +"Device.CWMP.": { + "type": "object", + "protocols": [ + "cwmp", + "usp" + ], + "array": false, + "access": false +} +``` + +**2. Object with instance:** + +- **UCI command:** uci show wireless | grep wifi-device + +```bash +"Device.X_IOPSYS_EU_Radio.{i}.": { + "type": "object", + "protocols": [ + "cwmp", + "usp" + ], + "array": true, + "access": true, + "mapping": { + "type": "uci", + "uci": { + "file": "wireless", + "section": { + "type": "wifi-device" + }, + "dmmapfile": "dmmap_wireless" + } + } +} +``` + +- **UBUS command:** ubus call dsl status | jsonfilter -e @.line + +```bash +"Device.DSL.Line.{i}.": { + "type": "object", + "protocols": [ + "cwmp", + "usp" + ], + "array": true, + "access": false, + "mapping": { + "type": "ubus", + "ubus": { + "object": "dsl", + "method": "status", + "args": {}, + "key": "line" + } + } +} +``` + +**3. Parameter under object with instance:** + +- **UCI option command:** uci get wireless.@wifi-device[0].country + +- **@i:** is the number of instance object + +```bash +"Country": { + "type": "string", + "protocols": [ + "cwmp", + "usp" + ], + "read": true, + "write": true, + "mapping": [ + { + "type" : "uci", + "uci" : { + "file" : "wireless", + "section" : { + "type": "wifi-device", + "index": "@i-1" + }, + "option" : { + "name" : "country" + } + } + } + ] +} +``` + +- **UCI list command:** uci get urlfilter.@profile[0].whitelist_url + +- **@i:** is the number of instance object + +```bash +"WhitelistURL": { + "type": "string", + "read": true, + "write": true, + "protocols": [ + "cwmp", + "usp" + ], + "list": { + "datatype": "string" + }, + "mapping": [ + { + "type": "uci", + "uci": { + "file": "urlfilter", + "section": { + "type": "profile", + "index": "@i-1" + }, + "list": { + "name": "whitelist_url" + } + } + } + ] +} +``` + + +- **UBUS command:** ubus call wifi status | jsonfilter -e @.radios[0].noise + +- **@i:** is the number of instance object + +```bash +"Noise": { + "type": "int", + "protocols": [ + "cwmp", + "usp" + ], + "read": true, + "write": false, + "mapping": [ + { + "type" : "ubus", + "ubus" : { + "object" : "wifi", + "method" : "status", + "args" : {}, + "key" : "radios[@i-1].noise" + } + } + ] +} +``` + +**4. Parameter without instance:** + +- **UCI option command:** uci get cwmp.cpe.userid + +```bash +"Username": { + "type": "string", + "protocols": [ + "cwmp", + "usp" + ], + "read": true, + "write": true, + "mapping": [ + { + "type" : "uci", + "uci" : { + "file" : "cwmp", + "section" : { + "type": "cwmp", + "name": "cpe" + }, + "option" : { + "name" : "userid" + } + } + } + ] +} +``` + +- **UCI list command:** uci get urlfilter.globals.blacklist_url + +- **@i:** is the number of instance object + +```bash +"BlacklistURL": { + "type": "string", + "read": true, + "write": true, + "protocols": [ + "cwmp", + "usp" + ], + "list": { + "datatype": "string" + }, + "mapping": [ + { + "type": "uci", + "uci": { + "file": "urlfilter", + "section": { + "name": "globals" + }, + "list": { + "name": "blacklist_url" + } + } + } + ] +} +``` + +- **UBUS command:** ubus call system info | jsonfilter -e @.uptime + +```bash +"Uptime": { + "type": "unsignedInt", + "protocols": [ + "cwmp", + "usp" + ], + "read": true, + "write": false, + "mapping": [ + { + "type" : "ubus", + "ubus" : { + "object" : "system", + "method" : "info", + "args" : {}, + "key" : "uptime" + } + } + ] +} +``` + +- **UBUS command:** ubus call system info | jsonfilter -e @.memory.total + +```bash +"Total": { + "type": "unsignedInt", + "protocols": [ + "cwmp", + "usp" + ], + "read": true, + "write": false, + "mapping": [ + { + "type" : "ubus", + "ubus" : { + "object" : "system", + "method" : "info", + "args" : {}, + "key" : "memory.total" + } + } + ] +} +``` + +**5. Parameter to map another data model Object:** + +- **UCI option command:** uci get urlfilter.@filter[0].profile + +- **linker_obj** is the path name of an object that is stacked immediately below this object + +```bash +"Profile": { + "type": "string", + "read": true, + "write": true, + "protocols": [ + "cwmp", + "usp" + ], + "mapping": [ + { + "type": "uci", + "uci": { + "file": "urlfilter", + "section": { + "type": "filter", + "index": "@i-1" + }, + "option": { + "name": "profile" + } + }, + "linker_obj": "Device.{BBF_VENDOR_PREFIX}URLFilter.Profile.*.Name" + } + ] +} +``` + +**6. Object with Event and Operate command:** + +```bash +{ + "Device.X_IOPSYS_Test.": { + "type": "object", + "protocols": [ + "cwmp", + "usp" + ], + "array": false, + "access": false, + "Push!": { + "type": "event", + "protocols": [ + "usp" + ], + "data": { + "type": "string", + "read": true, + "write": true, + "protocols": [ + "usp" + ] + } + }, + "Status()": { + "type": "command", + "async": true, + "protocols": [ + "usp" + ], + "input": { + "Option": { + "type": "string", + "read": "true", + "write": "true", + "protocols": [ + "usp" + ] + } + }, + "output": { + "Result": { + "type": "string", + "read": "true", + "write": "false", + "protocols": [ + "usp" + ] + } + }, + "mapping": [ + { + "type": "ubus", + "ubus": { + "object": "test", + "method": "status" + } + } + ] + } + } +} +``` ## How to add object dependency using Json plugin + In some cases we may need to set a dependency on datamodel object. In such cases the object will only populate if its dependencies are fulfilled. The json object `dependency` is used to define the same. Below is an example of how to add object dependency: + ```json { "json_plugin_version": 1, @@ -142,23 +622,6 @@ mapping: [ If we consider multi-instance objects, they are kind of special because we have group of information, where one group can be visualize as one instance. Also, the parameters of multi-instance objects also shares data with there parents, apart from that, for others as well, we might require some runtime information to get some mappings, for those scenarios, mapping have some special symbol, all start with '@' symbol, some of them only applicable in case of multi-instance object. Overall all these are just for create the convention so that datamodel can easily be extended without getting into hustle of programming. Again, the plugin handler does not have any intelligence of it own and completely driven by the mapping provided by the enduser, so if mapping is in-correct it would give incorrect result or no result in the datamodel. -## Special symbols - -@index => Current instance number - 1 - -@index - 1 => Parent instance number - 1 - -@index - 2 => Grand parent instance number - 1, and likewise - -@Name => Section name of parent - -@Parent => data passed by parent - -@Count => Returns the count of instances - -@Value => Replace with the value passed in set command, only used for ubus **set** - -@Input.XXX => Replace with the value passed in Input 'XXX' option, only used for ubus **operate** ## How to have different mappings for get/set: ```json @@ -452,7 +915,7 @@ Ubus example for the same - Uci list options can only be mapped to leaf dm nodes which show the values as csv list - It better to use a named config sections in place of unnamed config sections for multi-instance objects - Children on multi-instance objects needs to have reference to their parent using 'dm_parent' option in uci section like below: - + ```bash config agent 'agent' option timezone 'GMT0BST,M3.5.0/1,M10.5.0' @@ -465,17 +928,20 @@ config task_option 'http_get_mt_target' option dm_parent 'http_get_mt' option id 'target' ``` - + This object 'Device.LMAP.MeasurementAgent.{i}.Task.{i}.Option.{i}.' maps to the config above. It contains 3 Multi instance objects: 1. MeasurementAgent.{i}: parent object which maps to 'agent' section 2. Task.{i}: child object of MeasurementAgent object which maps to 'task' section, it must have a 'dm_parent' option with the value 'agent' 3. Option.{i}: child object of Task object which maps to 'task_option' section, it must have a 'dm_parent' option with the value 'http_get_mt' -## Feature supported with this mapping - - Use of `json_plugin_version` for mapping extensions - - Use different mappings for get/set - - Support for NumberOfEntries parameter - - Data sharing between parent and child node in multi-instance object - - Use of index number in mapping - - Support for set in ubus command +## Special symbols + +| Symbols | Meaning of the symbol | +| ------- | ---------------------- | +| @Name | Section name of parent | +| @Parent | data passed by parent | +| @Count | Returns the count of instances | +| @Value | Replace with the value passed in set command, only used for ubus **set** | +| @Input.XXX | Replace with the value passed in Input 'XXX' option, only used for ubus **operate** | + diff --git a/docs/guide/bbfdmd.md b/docs/guide/bbfdmd.md index a7d4de77..dbe85bc0 100644 --- a/docs/guide/bbfdmd.md +++ b/docs/guide/bbfdmd.md @@ -1,79 +1,26 @@ # BBFDM Daemon (bbfdmd) -`bbfdmd` is daemon which exposes data-model objects over ubus as required by [TR-069/cwmp](https://cwmp-data-models.broadband-forum.org/) or [TR-369/USP](https://usp.technology/). +`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/). -> Note 1: The command outputs shown in this readme are examples only, actual output may differ based on device and configuration. - -> Note 2: Long command outputs are compressed for better readability - -## UCI Config - -The configuration file is an `uci` file `/etc/config/bbfdm`. Sample configuration file is provided below. - -```bash -config bbfdmd 'bbfdmd' - option loglevel '2' - option sock '/tmp/bbfdm.sock' - option transaction_timeout 10 - option subprocess_level '1' - option refresh_time '10' -``` - -In the above uci, loglevel can have below value: - -|loglevel | Meaning | -|---------| -----------------------------------------| -| 0 | Disabled logging | -| 1 | Only errors will be logged | -| 2 | Only errors and warnings will be logged | -| 3 | Log everything except debug | -| 4 | Everything will be logged | - -For more info on the `bbfdmd` UCI configuration visit [uci documentation](../api/uci/bbfdm.md) OR [raw uci schema](../../schemas/uci/bbfdm.json) +> Note 1: The command outputs shown in this document are examples only, actual output may differ based on device and configuration. ## Concepts and Workflow -`bbfdmd` internally uses both `libbbfdm-api` and `libbbfdm` to get the data-model objects. On startup it parses the uci file to check the different configurations and then based on that it registers the `bbfdm` ubus namespace. +`bbfdmd` daemon gets started by `/etc/init.d/bbfdmd` service, bbfdmd init script reads the input from `bbfdm` uci file and then it generates the input for `bbfdmd` daemon in json format in `/tmp/bbfdm/input.json` -When a ubus method is called it first fills `bbfdm_data_t` structure with the necessary information, then proceeds the `Get/Set/Operate/Add/Del` operation based on that information. - -`bbfdmd` uses `bbf_entry_method` API from `libbbfdm-api` and `tEntryRoot`, `tVendorExtension`, `tVendorExtensionOverwrite` and `tVendorExtensionExclude` global shared arrays from `libbbfdm` to get the device tree schema and its values. - -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`. - -## Debugging tools -With the advancement in the datamodel tree, it is sometime required to do some debugging at the source, to simplify that `bbfdmd` offer a command line tool, which can - -- Work directly on plugins, or -- 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. - -```bash -# bbfdmd -h -Usage: bbfdmd [options] - -options: - -s ubus socket - -m json input configuration for micro services - -c Run cli command - -h Displays this help - -# -``` -If no command line option provided along with `bbfdmd` command then it starts in daemon mode and get the default configuration from `/etc/bbfdm/input.json` -```bash -# cat /etc/bbfdm/input.json +```json input.json { "daemon": { "config": { "loglevel": "1", - "refresh_time": "10", - "transaction_timeout": "10" + "refresh_time": "120", + "transaction_timeout": "30", + "subprocess_level": "2" }, "input": { "type": "DotSo", - "name": "/lib/libbbfdm.so" + "name": "/usr/share/bbfdm/libbbfdm.so", + "plugin_dir": "/usr/share/bbfdm/plugins" }, "output": { "type": "UBUS", @@ -96,6 +43,313 @@ If no command line option provided along with `bbfdmd` command then it starts in } ``` +When `bbfdmd` starts it parses the `input.json` file to check the different configurations, like +- Name of the TR181 datamodel definition file (daemon.input.name) +- Location of datamodel definition loaded as plugins (daemon.input.plugin_dir +- Name of the ubus object it has to register (daemon.output.name) + +`bbfdmd` daemon use `libbbfdm-api` library to traverse the datamodel tree added by 'libbbfdm' or other plugins added in predefined plugin path(daemon.input.plugin_dir). + +When a ubus method is called it first fills `bbfdm_data_t` structure with the necessary information, then proceeds the `Get/Set/Operate/Add/Del` operation based on that information. + +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. + +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`. + +`bbfdmd` daemon can also be used to expose a module specific datamodel or sub-tree, by using datamodel micro-services. Datamodel micro-service is nothing but another `bbfdmd` instance running with smaller data sub-set, micro-service can be identified in the runtime by running a `ps` command + +```bash +# ps|grep bbf + 3804 root 6968 S {dm_bridgemngr} /usr/sbin/bbfdmd -m bridgemngr + 3805 root 7064 S {dm_bulkdata} /usr/sbin/bbfdmd -m bulkdata + 3806 root 6900 S {dm_ddnsmngr} /usr/sbin/bbfdmd -m ddnsmngr + 3807 root 6996 S {dm_dhcpmngr} /usr/sbin/bbfdmd -m dhcpmngr +``` + +A `bbfdmd` instance with -m input means its running a module(sub-tree) datamodel. These micro-services exposed their own ubus objects + +```bash +# ubus list bbfdm.* +bbfdm.Bridging +bbfdm.BulkData +bbfdm.DHCPv4_DHCPv6 +bbfdm.DNS +``` + +When a datamodel started as micro-service, it looks/waits for `bbfdm` ubus object(added by main bbfdmd process), once its available micro-service resister with the main `bbfdmd` process by calling it 'service' method + +```bash +# ubus -v list bbfdm +'bbfdm' @e970413c + "service":{"cmd":"String","name":"String","parent_dm":"String","objects":"Array"} +``` + +More details about micro-services covered in a dedicated section. + +> Note: 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. + +## Input and output Schema(s) + +`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) + +`bbfmdd` can also be used to expose sub tree using different ubus object by using datamodel micro-service, ubus guide and schema for datamodel micro-services + +- [datamodel micro-service](../api/ubus/bbfdm_micro_service.md) +- [datamodel micro-service schema](../api/ubus/bbfdm_micro_service.json) + +Apart from these, datamodel micro-services can also be configured by updating their input files directly at the runtime, micro-service input files present in `/etc/bbfdm/micro_services/` in CPE. + +Datamodel micro-service has a similar input file as of main bbfdmd + +```json +{ + "daemon": { + "enable": "1", + "service_name": "sshmngr", + "config": { + "loglevel": "1" + } + } +} +``` + +### Ubus methods + +Following are the ubus methods exposed by `bbfdmd` main process: + +```bash +# ubus -v list bbfdm +'bbfdm' @9e9928ef + "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","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"} + "transaction":{"cmd":"String","timeout":"Integer","restart_services":"Boolean","optional":"Table"} + "service":{"cmd":"String","name":"String","parent_dm":"String","objects":"Array"} + "notify_event":{"name":"String","input":"Table"} +``` + +Each datamodel micro-service expose their own ubus object, which is slightly different from main `bbfdm` ubus object, following is an example of ubus methods exposed by datamodel micro-services. + +```bash +# ubus -v list bbfdm.SSH +'bbfdm.SSH' @bb8a66da + "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","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"} + "transaction":{"cmd":"String","timeout":"Integer","restart_services":"Boolean","optional":"Table"} +``` + +> Note1: `optional` table are present in all methods and it supports below options: + +```console +"optional":{"proto":"String", "instance_mode":"Integer", "transaction_id":"Integer", "format":"String"} +``` + + - `proto` in each method specify the data-model prototype('cwmp', 'usp') to use, if not provided default data-model will be used. + + - `instance_mode` could be 0 or 1, for instance number, instance alias respectively. + + - `transaction_id` to define the transaction id number. + + - `format` could be 'raw' or 'pretty', to specify the format to use as output, if not provided 'pretty' format will be used. + +> 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 + +### Fault handling + +To indicate a fault and source of fault `bbfdmd` provides `fault` along with `fault_msg` in the response in case of faults, which then handled by higher layer applications (i.e 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). + +#### Example(s) + +1. The requested value is correct as per TR181 standard, but there is a limitation in the device. + +```console +root@iopsys:~# ubus call bbfdm set '{"path":"Device.Firewall.Config", "value":"High"}' +{ + "results": [ + { + "path": "Device.Firewall.Config", + "fault": 9007, + "fault_msg": "The current Firewall implementation supports only 'Advanced' config." + } + ] +} +``` + +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"}' +{ + "results": [ + { + "path": "Device.Firewall.Chain.1.Rule.9.DestPort", + "fault": 9007, + "fault_msg": "'123456' value is not within range (min: '-1' max: '65535')" + } + ] +} +``` + +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":{}}' +{ + "results": [ + { + "path": "Device.IP.Diagnostics.IPPing()", + "data": "ipping_test", + "fault": 7004, + "fault_msg": "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." + +```console +root@iopsys:~# ubus call bbfdm get '{"path":"Users.User.", "optional": {"format":"raw", "proto":"usp"}}' +{ + "results": [ + { + "path": "Users.User.", + "fault": 7026, + "fault_msg": "Path is not present in the data model schema" + } + ] +} +``` + +These fault messages defined in datamodel handlers, user 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. + +##### Errors 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 +- `get` calls depends on uci option 'bbfdm.bbfdmd.subprocess_level' (default: 2) + + +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:~# +``` + +## Datamodel micro-services + +Datamodel micro-service is nothing but running a partial datamodel sub-set with another instance of `bbfdmd` binary. + +Benefit: +- Instead of having a huge datamodel tree, it split the tree based on modules, which reduce the cost of operation on the tree +- Resolves one point failure, if any datamodel micro-service not working correctly it only affects that specific module, not the rest of the tree +- Moving datamodel code to module repo, brings the service layer and datamodel layer closer, which lowers the possibilities of wrong mapping +- Possible to use lightweight `bbfdmd` inside containers with json plugin for Container service management +- Possible to impose CPU/Memory restrictions or even run it in a procd jail to limit the host resource access + +Cons: +- It requires to execute a `bbfdmd` instance each module, so takes bit more resouces +- Resolving of complex datamodel paths, like datamodel references of external modules (ex: `bridgemngr` refers to wifi layer from `wifidmd`) cost more on IPC + +When not to use micro-service: +- Its suggested not to use datamodel micro-service specially in the devices which are having very less resources(in terms of memory/cpu), or +- On devices which have high IPC cost over ubus + +### How to Use micro-service + +Manually configuring and starting a micro-services requires multiple steps, but its made simple by using `bbfdm.mk` compile time helper utility. +To launch a datamodel definition as a datamodel micro-service, user need to install the datamodel definition/plugin using + +`BBFDM_INSTALL_MS_DM` API from `bbfdm.mk` + + +```bash +bulkdata/Makefile: $(BBFDM_INSTALL_MS_DM) $(PKG_BUILD_DIR)/bbf_plugin/bulkdata.json $(1) $(PKG_NAME) +ddnsmngr/Makefile: $(BBFDM_INSTALL_MS_DM) $(PKG_BUILD_DIR)/src/libddnsmngr.so $(1) $(PKG_NAME) +``` + +Please check [bbfdm.mk](https://dev.iopsys.eu/feed/iopsys/-/blob/devel/bbfdm/bbfdm.mk) documentation for more details. + +In Devices, datamodel micro-services started and managed by `/etc/init.d/bbfdm.services` init script, which reads the global micro-service related configuration from `bbfdm` uci file, and reads module specific configuration for each module's input file present in `/etc/bbfdm/micro_services/` directory. + + +> In plugins approach, the 3rd party datamodel gets attached to main bbfdm process, which further increases nodes in main datamodel tree, which overtime become a huge tree, results in slower turn around service time for the APIs. Also, any unhandled fault in plugin result in segfault in main bbfdmd process, which takes down the whole tree along with plugin, resulting in complete failure from cwmp and USP, with micro-services plugins runs as an individual processes, so impact of fault limited to its own micro-service only. + +Micro-service approach, disintegrate the plugins further and run them as individual daemons with the help of "bbfdmd" "-m" command line options. +## Datamodel debugging tools + +To debug the datamodel objects/parameters, `bbfdmd` provides a command line interface, which can + +- Work directly on plugins, or +- 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. + +```bash +# bbfdmd -h +Usage: bbfdmd [options] + +options: + -s ubus socket + -m json input configuration for micro services + -c Run cli command + -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. ```bash @@ -111,90 +365,77 @@ Valid commands: # ``` -Below is another example of json input file: +To debug datamodel mapping/description code, user/developer can use below API to add debug logs + +```bash +BBF_ERR(MESSAGE, ...) +BBF_WARNING(MESSAGE, ...) +BBF_INFO(MESSAGE, ...) +BBF_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. + +To configure the log_level in micro-service, update the `loglevel` module json file, ```json +# cat /etc/bbfdm/micro_services/sshmngr.json { - "cli": { - "config": { - "proto": "usp", // usp, cwmp - "instance_mode": 0 // 0:number, 1:alias - }, - "input": { - "type": "UBUS", // JSON, UBUS, DotSO, UNIX - "name": "bbfdm" - }, - "output": { - "type": "CLI" // CLI, JSON - } + "daemon": { + "enable": "1", + "service_name": "sshmngr", + "config": { + "loglevel": "1" } + } } ``` -> NOTE1: `bbfdmd` CLI mode is an experimentation feature and it can be updated later. +and then restart the bbfdm.services -> NOTE2: If `-m` option is not passed when starting `bbfdmd`, so configuration options will be loaded from the default [INPUT.JSON](../../test/files/tmp/bbfdm/input.json) located in '/tmp/bbfdm/input.json'. +## How to extend datamodel -* To see the currently implemented data model use: +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. -```console -$ bbfdmd -c schema Device. -``` +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." -* To query the value of a parameter use: +Please check [TR106](https://www.broadband-forum.org/pdfs/tr-106-1-13-0.pdf) for more details about datamodel terminology. -```console -root@iopsys:~# bbfdmd -c get Device.Time. -Device.Time.Enable => 0 -root@iopsys:~# -root@iopsys:~# bbfdmd -c get Device.WiFi.SSID.1.SSID -Device.WiFi.SSID.1.SSID => test-5g -``` +`bbfdm` provide the tools and utilities to further extend/overwrite/disable the datamodel using C-code or simply by using JSON datamodel definition. -> Note: Wildcard (*) is valid placeholder for multi-instance object instance and partial paths are also allowed. +### 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) -* To set the value of a data model parameter use: +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) -```console -$ bbfdmd -c set "parameter" "value" -``` +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: The CLI mode also supports adding and deleting instances of data model objects and supported instances. +> 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 -## Important topics -* [UBUS methods](bbfdmd_ubus_methods.md) -* [UBUS Errors](bbfdmd_ubus_errors.md) -* [Parallel UBUS call](bbfdmd_ubus_parallel_call.md) -* [Third party datamodel integration](bbfdmd_dm_integration.md) +C/JSON both datamodel definition support defining all datamodel operations, but JSON should be used with simple datamodel deployments. - -## Dependencies - -### Build-Time Dependencies - -To successfully build bbfdmd, following libraries are needed: - -| Dependency | Link | License | -| ---------- | ------------------------------------------- | -------------- | -| libuci | https://git.openwrt.org/project/uci.git | LGPL 2.1 | -| libubox | https://git.openwrt.org/project/libubox.git | BSD | -| libubus | https://git.openwrt.org/project/ubus.git | LGPL 2.1 | -| libjson-c | https://s3.amazonaws.com/json-c_releases | MIT | -| libbbfdm-api | 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 | https://dev.iopsys.eu/bbf/bbfdm.git | BSD-3 | - - -System daemon `ubusd` is used to expose the BBFDM functionality over `ubus`. +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/bbfdmd_dm_integration.md b/docs/guide/bbfdmd_dm_integration.md deleted file mode 100644 index cd8534fc..00000000 --- a/docs/guide/bbfdmd_dm_integration.md +++ /dev/null @@ -1,213 +0,0 @@ -# Third party data model integration - -It is also possible to itegrate thrid party data model to the bbfdmd to expose it to the ubus. To do so certain APIs in libbbfdm-api needs to be implemented to make the data model compatible with bbfdmd. APIs are described below. - - -## List of libbbfdm-api methods used in bbfdmd to integrate third party data model - -### Refernces -Deatils of libbbfdm-api can be found at [link](../../docs) - -following are the libbbfdm-api methods used in bbfdmd to access the data model defined in libbbfdm - -``` -bbf_entry_method -bbf_ctx_init -bbf_ctx_init_sub -bbf_ctx_clean -bbf_ctx_clean_sub -bbf_entry_restart_services -bbf_entry_revert_changes -``` - -## Methods -Description of the methods are given below - -### bbf_entry_method - -used to read the data model based on the input given - -``` -int bbf_entry_method(struct dmctx *ctx, int cmd) - -inputs - struct dmctx *ctx - pointer to struct dmctx strunture. The list of parameter will be updated in ctx.list_parameter. each node in the list is of type - struct dm_parameter which contains char *name, char *data, char *type and char *additional_data; - the content of fields are updated based on the cmd and are as follows- - cmd | Name | Type | Data | Addtional Data | - |------------- |------------- |------------- |------------ |--------------------- | - |BBF_GET_VALUE |Parameter |$ref(type) |Value | NA | - |BBF_GET_NAME |Parameter |$ref(type) |writable(0/1) | NA | - |BBF_SET_VALUE |path | NA | NA | NA | - |BBF_ADD_OBJECT |path | NA | NA | NA | - |BBF_DEL_OBJECT |path | NA | NA | NA | - |BBF_OPERATE |path | NA | NA | NA | - |BBF_SCHEMA |paramter ||$ref(type) |writable(0/1) |unique keys | - |BBF_INSTANCES |parameter | NA |NA |NA | - |BBF_EVENT |path | NA | NA | NA | - - int cmd - command to API to tell how the data model is to be read, possible values are - BBF_GET_VALUE - Read the values of the parameters from data model - BBF_GET_NAME - Read the names of the parameters from data model - BBF_SET_VALUE - Set value of specified parameters in the data model - BBF_ADD_OBJECT - Add object in a multi instance parameter in the data model - BBF_DEL_OBJECT - Delete object from a multi instance parameter in the data model - BBF_OPERATE - execute the specified command - BBF_SCHEMA - Read all the parameter type parameter from data model. - BBF_INSTANCES - Read all the instance of multi instance parameter from data model. - BBF_EVENT - execute the specified event - -return - int fault - contains the fault code if API is not able to read the data model. returns 0 on success. -``` - -### bbf_ctx_init - -This method is used to initialize the dmctx structure object to read the data model. - -``` -void bbf_ctx_init(struct dmctx *ctx, DMOBJ *tEntryObj); -inputs - struct dmctx *ctx - pointer to struct dmctx strunture to be initialized. - -return - None -``` - -### bbf_ctx_init_sub - -This method is an extension of bbf_ctx_init method. only difference it only intializes dmctx structure object and does not intializes other resources used in reading data model - -``` -void bbf_ctx_init_sub(struct dmctx *ctx, DMOBJ *tEntryObj) -inputs - struct dmctx *ctx - pointer to struct dmctx strunture to be initialized. - -return - None -``` - - -### bbf_ctx_clean - -This method is used to free the dmctx structure object and other resources post reading the data model. - -``` -void bbf_ctx_clean(struct dmctx *ctx) - -input - struct dmctx *ctx - pointer to struct dmctx strunture to be freed. - -return - None -``` - -### bbf_ctx_clean_sub - -This method is an extension of bbf_ctx_clean method. only difference is it frees the dmctx structure and does not free other resources used in reading data model - -``` -void bbf_ctx_clean_sub(struct dmctx *ctx) - -input - struct dmctx *ctx - pointer to struct dmctx strunture to be freed. - -return - None -``` - -### bbf_entry_restart_services - -This method is used to restart the state of data model whenever its state is changed - -``` -void bbf_entry_restart_services(struct blob_buf *bb, bool restart_services) - -input - struct blob_buf *bb - pointer to the struct blob_buf object. contains all the packages updated. - - bool restart_services - if true packages will be updated through ubus call. - if false packages will be updated through uci. - -return - None -``` -### bbf_entry_revert_changes - -This method is used to revert the changes whenever its state is changed - -``` -void bbf_entry_revert_changes(struct blob_buf *bb) - -input - struct blob_buf *bb - pointer to the struct blob_buf object. contains all the packages updated. - -return - None -``` - -### Datamodel Tree -`libbbfdm-api` provides API to easily extend and define datamodel tree. - -#### Alias handling -In general datamodel parameters with multi-instance objects has a parameter named as '.Alias' to uniquely identify the instance. libbbf-api provides two generic APIs to handle the get/set of Alias parameters. - -These APIs only applicable for standard/dmmap uci mappings. -```bash -/*********************************************************************//** -** -** bbf_get_alias -** -** This API is used to get the Alias parameter value based on s and option_name -** -** \param ctx - bbf context -** \param s - uci section from where will get Alias value -** \param option_name - option name -** \param instance - instance value -** \param value - pointer to where the value will be stored -** -** \return 0 if operation is successful, -1 otherwise -** -**************************************************************************/ -int bbf_get_alias(struct dmctx *ctx, struct uci_section *s, char *option_name, char *instance, char **value); - -/*********************************************************************//** -** -** bbf_set_alias -** -** This API is used to set the Alias parameter value -** -** \param ctx - bbf context -** \param s - uci section to where will save Alias value -** \param option_name - option name -** \param instance - instance value -** \param value - the value to be set -** -** \return 0 if operation is successful, -1 otherwise -** -**************************************************************************/ -int bbf_set_alias(struct dmctx *ctx, struct uci_section *s, char *option_name, char *instance, char *value); -``` - -Example: -```bash -static int get_WiFiEndPoint_Alias(char *refparam, struct dmctx *ctx, void *data, char *instance, char **value) -{ - return bbf_get_alias(ctx, ((struct dm_data *)data)->dmmap_section, "endpointalias", instance, value); -} - -static int set_WiFiEndPoint_Alias(char *refparam, struct dmctx *ctx, void *data, char *instance, char *value, int action) -{ - return bbf_set_alias(ctx, ((struct dm_data *)data)->dmmap_section, "endpointalias", instance, value); -} -``` diff --git a/docs/guide/bbfdmd_event.md b/docs/guide/bbfdmd_event.md deleted file mode 100644 index f17c8cc3..00000000 --- a/docs/guide/bbfdmd_event.md +++ /dev/null @@ -1,70 +0,0 @@ -# Monitoring Events in the Data Model - -`bbfdmd` now supports monitoring events directly from the Data Model, eliminating the need for internal registration and handling within `bbfdmd`. - -# How to add an new event - -- Insert the event into the required `DMLEAF` table - -- Ensure that `leaf_type` is defined as `DMT_EVENT` and `bbfdm_type` as `BBFDM_USP` - -- Implement the get/set event API - -# How it works - -Upon starting `bbfdmd`, it calls `bbf_entry_method` API with `BBF_SCHEMA` method to retrieve all events supported by Data Model. Subsequently, it attempts to register an event handler for each event by using the event name argument defined in each event leaf and then listens for that event name. - -When the event name is triggered, `bbfdmd` calls `bbf_entry_method` API with `BBF_EVENT` method to perform the event operation. And finally, it sends `bbfdm.event` ubus event with the required input information obtained from the returned event operation. - -# Event Example - -Below is an example of `Device.WiFi.DataElements.AssociationEvent.Associated!` event implementation: - -static event_args wifidataelementsassociationevent_associated_args = { - .name = "wifi.dataelements.Associated", - .param = (const char *[]) { - "type", - "version", - "protocols", - "BSSID", - "MACAddress", - "StatusCode", - "HTCapabilities", - "VHTCapabilities", - "HECapabilities", - "TimeStamp", - NULL - } -}; - -static int get_event_args_WiFiDataElementsAssociationEvent_Associated(char *refparam, struct dmctx *ctx, void *data, char *instance, char **value) -{ - *value = (char *)&wifidataelementsassociationevent_associated_args; - return 0; -} - -static int event_WiFiDataElementsAssociationEvent_Associated(char *refparam, struct dmctx *ctx, void *data, char *instance, char *value, int action) -{ - switch (action) { - case EVENT_CHECK: - // Nothing to check - break; - case EVENT_RUN: - char *event_time = dmjson_get_value((json_object *)value, 1, "eventTime"); - char *bssid = dmjson_get_value((json_object *)value, 3, "wfa-dataelements:AssociationEvent.AssocData", "DisassocData", "BSSID"); - char *mac_addr = dmjson_get_value((json_object *)value, 3, "wfa-dataelements:AssociationEvent.AssocData", "DisassocData", "MACAddress"); - - add_list_parameter(ctx, dmstrdup("TimeStamp"), dmstrdup(event_time), DMT_TYPE[DMT_STRING], NULL); - add_list_parameter(ctx, dmstrdup("BSSID"), dmstrdup(bssid), DMT_TYPE[DMT_STRING], NULL); - add_list_parameter(ctx, dmstrdup("MACAddress"), dmstrdup(mac_addr), DMT_TYPE[DMT_STRING], NULL); - break; - } - - return 0; -} - -DMLEAF tWiFiDataElementsAssociationEventParams[] = { -/* PARAM, permission, type, getvalue, setvalue, bbfdm_type*/ -{"Associated!", &DMREAD, DMT_EVENT, get_event_args_WiFiDataElementsAssociationEvent_Associated, event_WiFiDataElementsAssociationEvent_Associated, BBFDM_USP}, -{0} -}; \ No newline at end of file diff --git a/docs/guide/bbfdmd_ubus_errors.md b/docs/guide/bbfdmd_ubus_errors.md deleted file mode 100644 index a4a2064b..00000000 --- a/docs/guide/bbfdmd_ubus_errors.md +++ /dev/null @@ -1,197 +0,0 @@ -# UBUS Errors - -Today, in addional to the `CWMP` and `USP` standard error messages, bbfdm has introduced a new feature to provide customers more clarification about the root cause of the fault, -and based on that it's easily to understand what the issue is and how to fix it and find out the limitations we have on the device. - -Whenever you encounter an error in a specific method(GET/SET/ADD/DELETE/OPERATE), you can use the `fault_msg` option to understand the reason for the error. - -## Example of fault messages - -1. The requested value is correct as per TR181 standard, but there is a limitation in the device. - -```console -root@iopsys:~# ubus call bbfdm set '{"path":"Device.Firewall.Config", "value":"High"}' -{ - "results": [ - { - "path": "Device.Firewall.Config", - "fault": 9007, - "fault_msg": "The current Firewall implementation supports only 'Advanced' config." - } - ] -} - -root@iopsys:~# ubus call bbfdm set '{"path":"Device.Firewall.AdvancedLevel", "value":"Device.Firewall.Level.2"}' -{ - "results": [ - { - "path": "Device.Firewall.AdvancedLevel", - "fault": 9007, - "fault_msg": "The current Firewall implementation supports only one Level. So the value should be 'Device.Firewall.Level.1'." - } - ] -} -``` - -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"}' -{ - "results": [ - { - "path": "Device.Firewall.Chain.1.Rule.9.DestPort", - "fault": 9007, - "fault_msg": "'123456' value is not within range (min: '-1' max: '65535')" - } - ] -} -``` - -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":{}}' -{ - "results": [ - { - "path": "Device.IP.Diagnostics.IPPing()", - "data": "ipping_test", - "fault": 7004, - "fault_msg": "IPPing: 'Host' input should be defined" - } - ] -} -``` - -4. The requested method is not permitted since the instance was created by the system. - -```console -root@iopsys:~# ubus call bbfdm add '{"path":"Device.Firewall.Chain.2.Rule."}' -{ - "results": [ - { - "path": "Device.Firewall.Chain.2.Rule.", - "fault": 9003, - "fault_msg": "This is a dynamic 'Chain' instance which is created by 'Port Mapping', so it's not permitted to add a static 'Rule'." - } - ] -} - -root@iopsys:~# ubus call bbfdm del '{"path":"Device.Firewall.Chain.1.Rule.1."}' -{ - "results": [ - { - "path": "Device.Firewall.Chain.1.Rule.1.", - "fault": 9003, - "fault_msg": "This is a dynamic 'Rule' instance, therefore it's not permitted to delete it." - } - ] -} -``` - -> Note: If no specific fault message defined for particular obj/param, we return the standard error messages that are defined in CWMP and USP protocols as the fault message value. - -## Path syntax and possible error cases - -Please note some error scenerios with the bbfdm. - -1. 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"}}' -{ - "results": [ - { - "path": "Users.User.", - "fault": 7026, - "fault_msg": "Path is not present in the data model schema" - } - ] -} - -``` - -2. The path parameter must end with a '.' if the path element is not a leaf element e.g., - Note that first two commands doesn't end with a '.' while the command with Alias is correct, due to Alias - being the leaf element. To find correct schema path user can check with dump_schema option. - -```console -root@iopsys:~# -root@iopsys:~# ubus call bbfdm get '{"path":"Device.Users.User.4", "optional": {"format":"raw", "proto":"usp"}}' -{ - "results": [ - { - "path": "Device.Users.User.4", - "fault": 7026, - "fault_msg": "Path is not present in the data model schema" - } - ] -} -root@iopsys:~# -root@iopsys:~# ubus call bbfdm get '{"path":"Device.Users.User.*", "optional": {"format":"raw", "proto":"usp"}}' -{ - "results": [ - { - "path": "Device.Users.User.*", - "fault": 7008, - "fault_msg": "Requested path was invalid or a reference was invalid" - } - ] -} -root@iopsys:~# -root@iopsys:~# ubus call bbfdm get '{"path":"Device.Users.User.4.Alias", "optional": {"format":"raw", "proto":"usp"}}' -{ - "results": [ - { - "path": "Device.Users.User.4.Alias", - "data": "cpe-4", - "type": "xsd:string" - } - ] -} -``` - -3. The path parameter value must use proper '.' separated path search expression. Note that a '.' is missing between User and * - -```console -root@eagle-44d43771b550:~# ubus call bbfdm get '{"path":"Device.Users.User.*", "optional": {"format":"raw", "proto":"usp"}}' -{ - "results": [ - { - "path": "Device.Users.User.*", - "fault": 7008, - "fault_msg": "Requested path was invalid or a reference was invalid" - } - ] -} -``` - -4. The path parameter value must be a valid path schema, in example below SSID is used which is invalid schema element for Device.Users.User.{i}. - -```console -root@iopsys:~# ubus call bbfdm get '{"path":"Device.Users.User.1.SSID", "optional": {"format":"raw", "proto":"usp"}}' -{ - "results": [ - { - "path": "Device.Users.User.1.SSID", - "fault": 7026, - "fault_msg": "Path is not present in the data model schema" - } - ] -} -``` - -#### Errors 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. | diff --git a/docs/guide/bbfdmd_ubus_methods.md b/docs/guide/bbfdmd_ubus_methods.md deleted file mode 100644 index 168e2436..00000000 --- a/docs/guide/bbfdmd_ubus_methods.md +++ /dev/null @@ -1,1259 +0,0 @@ -# UBUS Methods - -`bbfdmd` needs to be started on startup after `ubusd`, as it exposes the data-model objects over `ubus`. - -```console -root@iopsys:~# ubus list |grep bbfdm -bbfdm -``` - -`usp` namespace is to provide the output as required by `End User` or in pretty format, which can be used easliy by other front-end applications(like: `obuspa`, `icwmp`). - - -`bbfdmd` namespace provides many methods with functionalities: - -```console -root@iopsys:~# ubus -v list bbfdm -'bbfdm' @17924c56 - "get":{"path":"String","paths":"Array","maxdepth":"Integer","optional":"Table"} - "schema":{"path":"String","paths":"Array","first_level":"Boolean","commands":"Boolean","events":"Boolean","params":"Boolean","optional":"Table"} - "instances":{"path":"String","paths":"Array","first_level":"Boolean","optional":"Table"} - "set":{"path":"String","value":"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"} - "transaction":{"cmd":"String","timeout":"Integer","restart_services":"Boolean","optional":"Table"} - "notify_event":{"name":"String","input":"Table"} -root@iopsys:~# -``` - -> Note1: `optional` table are present in all methods and it supports below options: - -```console -"optional":{"proto":"String", "instance_mode":"Integer", "transaction_id":"Integer", "format":"String"} -``` - - - `proto` in each method specify the data-model prototype('cwmp', 'usp') to use, if not provided default data-model will be used. - - - `instance_mode` could be 0 or 1, for instance number, instance alias respectively. - - - `transaction_id` to define the transaction id number. - - - `format` could be 'raw' or 'pretty', to specify the format to use as output, if not provided 'pretty' format will be used. - -> 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 - -The objects registered with the above namespace can be called with appropriate parameters to perform a `Get/Set/Operate/Add Object/Delete Object` operation as below. - -## Overview - -`bbfdmd` provides below functionality in pretty or raw formats using supported commands: - - - Get single value - - Get multiple values - - Set single value - - Set multiple values - - Operate - - Add object - - Add object and setting its parameters - - Delete single object - - Delete multiple objects - - Object names - - Instances - - schema - - Transaction start - - Transaction status - - Transaction commit - - Transaction abort - - Send notification for an event - - -### Get single value -API to query the value of a specific object. - -```console -root@iopsys:~# ubus call bbfdm get '{"path":"Device.IP.Diagnostics.", "optional": {"proto":"usp"}}' -{ - "Diagnostics": { - "IPv4PingSupported": true, - "IPv6PingSupported": true, - "IPv4TraceRouteSupported": true, - "IPv6TraceRouteSupported": true, - "IPv4DownloadDiagnosticsSupported": true, - "IPv6DownloadDiagnosticsSupported": true, - "IPv4UploadDiagnosticsSupported": true, - "IPv6UploadDiagnosticsSupported": true, - "IPv4UDPEchoDiagnosticsSupported": true, - "IPv6UDPEchoDiagnosticsSupported": true, - "IPv4ServerSelectionDiagnosticsSupported": true, - "IPv6ServerSelectionDiagnosticsSupported": true, - "IPLayerCapacitySupported": true, - "IPLayerMaxConnections": 1, - "IPLayerMaxIncrementalResult": 3600, - "IPLayerCapSupportedSoftwareVersion": "7.5.1", - "IPLayerCapSupportedControlProtocolVersion": 9, - "IPLayerCapSupportedMetrics": "IPLR,Sampled_RTT,IPDV,IPRR,RIPR", - "UDPEchoConfig": { - "Enable": false, - "Interface": "", - "SourceIPAddress": "", - "UDPPort": 0, - "EchoPlusEnabled": false, - "EchoPlusSupported": true, - "PacketsReceived": 0, - "PacketsResponded": 0, - "BytesReceived": 0, - "BytesResponded": 0, - "TimeFirstPacketReceived": "0001-01-01T00:00:00.000000Z", - "TimeLastPacketReceived": "0001-01-01T00:00:00.000000Z" - } - } -} -root@iopsys:~# -root@iopsys:~# ubus call bbfdm get '{"path":"Device.IP.Diagnostics.", "optional": {"proto":"cwmp"}}' -{ - "Diagnostics": { - "IPv4PingSupported": true, - "IPv6PingSupported": true, - "IPv4TraceRouteSupported": true, - "IPv6TraceRouteSupported": true, - "IPv4DownloadDiagnosticsSupported": true, - "IPv6DownloadDiagnosticsSupported": true, - "IPv4UploadDiagnosticsSupported": true, - "IPv6UploadDiagnosticsSupported": true, - "IPv4UDPEchoDiagnosticsSupported": true, - "IPv6UDPEchoDiagnosticsSupported": true, - "IPv4ServerSelectionDiagnosticsSupported": true, - "IPv6ServerSelectionDiagnosticsSupported": true, - "IPLayerCapacitySupported": true, - "IPPing": { - "DiagnosticsState": "None", - "Interface": "", - "ProtocolVersion": "Any", - "Host": "", - "NumberOfRepetitions": 3, - "Timeout": 1000, - "DataBlockSize": 64, - "DSCP": 0, - "IPAddressUsed": "", - "SuccessCount": 0, - "FailureCount": 0, - "AverageResponseTime": 0, - "MinimumResponseTime": 0, - "MaximumResponseTime": 0, - "AverageResponseTimeDetailed": 0, - "MinimumResponseTimeDetailed": 0, - "MaximumResponseTimeDetailed": 0 - }, - "TraceRoute": { - "DiagnosticsState": "None", - "Interface": "", - "ProtocolVersion": "Any", - "Host": "", - "NumberOfTries": 3, - "Timeout": 5000, - "DataBlockSize": 72, - "DSCP": 0, - "MaxHopCount": 30, - "ResponseTime": 0, - "IPAddressUsed": "", - "RouteHopsNumberOfEntries": 0 - } - } -} -root@iopsys:~# -root@iopsys:~# ubus call bbfdm get '{"path":"Device.Users."}' -{ - "Users": { - "UserNumberOfEntries": 3, - "GroupNumberOfEntries": 2, - "RoleNumberOfEntries": 0, - "SupportedShellNumberOfEntries": 1, - "User": [ - { - "Alias": "cpe-1", - "Enable": true, - "UserID": 0, - "Username": "root", - "Password": "", - "RemoteAccessCapable": false, - "GroupParticipation": "Device.Users.Group.1", - "RoleParticipation": "", - "StaticUser": true, - "Language": "", - "Shell": "Device.Users.SupportedShell.1" - }, - { - "Alias": "cpe-2", - "Enable": true, - "UserID": 1, - "Username": "daemon", - "Password": "", - "RemoteAccessCapable": false, - "GroupParticipation": "Device.Users.Group.2", - "RoleParticipation": "", - "StaticUser": true, - "Language": "", - "Shell": "" - }, - { - "Alias": "cpe-3", - "Enable": true, - "UserID": 55, - "Username": "ftp", - "Password": "", - "RemoteAccessCapable": false, - "GroupParticipation": "Device.Users.Group.8", - "RoleParticipation": "", - "StaticUser": true, - "Language": "", - "Shell": "" - } - ], - "Group": [ - { - "Alias": "cpe-1", - "Enable": true, - "GroupID": 0, - "Groupname": "root", - "RoleParticipation": "", - "StaticGroup": true - }, - { - "Alias": "cpe-2", - "Enable": true, - "GroupID": 1, - "Groupname": "daemon", - "RoleParticipation": "", - "StaticGroup": true - } - ], - "SupportedShell": [ - { - "Alias": "cpe-1", - "Enable": true, - "Name": "ash" - } - ] - } -} -root@iopsys:~# -root@iopsys:~# ubus call bbfdm get '{"path":"Device.Users.", "optional": {"format":"raw"}}' -{ - "results": [ - { - "path": "Device.Users.UserNumberOfEntries", - "data": "3", - "type": "xsd:unsignedInt" - }, - { - "path": "Device.Users.GroupNumberOfEntries", - "data": "2", - "type": "xsd:unsignedInt" - }, - { - "path": "Device.Users.RoleNumberOfEntries", - "data": "0", - "type": "xsd:unsignedInt" - }, - { - "path": "Device.Users.SupportedShellNumberOfEntries", - "data": "1", - "type": "xsd:unsignedInt" - }, - { - "path": "Device.Users.User.1.Alias", - "data": "cpe-1", - "type": "xsd:string" - }, - { - "path": "Device.Users.User.1.Enable", - "data": "1", - "type": "xsd:boolean" - }, - { - "path": "Device.Users.User.1.UserID", - "data": "0", - "type": "xsd:unsignedInt" - }, - { - "path": "Device.Users.User.1.Username", - "data": "root", - "type": "xsd:string" - }, - { - "path": "Device.Users.User.1.Password", - "data": "", - "type": "xsd:string" - }, - { - "path": "Device.Users.User.1.RemoteAccessCapable", - "data": "0", - "type": "xsd:boolean" - }, - { - "path": "Device.Users.User.1.GroupParticipation", - "data": "Device.Users.Group.1", - "type": "xsd:string" - }, - { - "path": "Device.Users.User.1.RoleParticipation", - "data": "", - "type": "xsd:string" - }, - { - "path": "Device.Users.User.1.StaticUser", - "data": "1", - "type": "xsd:boolean" - }, - { - "path": "Device.Users.User.1.Language", - "data": "", - "type": "xsd:string" - }, - { - "path": "Device.Users.User.1.Shell", - "data": "Device.Users.SupportedShell.1", - "type": "xsd:string" - }, - { - "path": "Device.Users.User.2.Alias", - "data": "cpe-2", - "type": "xsd:string" - }, - { - "path": "Device.Users.User.2.Enable", - "data": "1", - "type": "xsd:boolean" - }, - { - "path": "Device.Users.User.2.UserID", - "data": "1", - "type": "xsd:unsignedInt" - }, - { - "path": "Device.Users.User.2.Username", - "data": "daemon", - "type": "xsd:string" - }, - { - "path": "Device.Users.User.2.Password", - "data": "", - "type": "xsd:string" - }, - { - "path": "Device.Users.User.2.RemoteAccessCapable", - "data": "0", - "type": "xsd:boolean" - }, - { - "path": "Device.Users.User.2.GroupParticipation", - "data": "Device.Users.Group.2", - "type": "xsd:string" - }, - { - "path": "Device.Users.User.2.RoleParticipation", - "data": "", - "type": "xsd:string" - }, - { - "path": "Device.Users.User.2.StaticUser", - "data": "1", - "type": "xsd:boolean" - }, - { - "path": "Device.Users.User.2.Language", - "data": "", - "type": "xsd:string" - }, - { - "path": "Device.Users.User.2.Shell", - "data": "", - "type": "xsd:string" - }, - { - "path": "Device.Users.User.3.Alias", - "data": "cpe-3", - "type": "xsd:string" - }, - { - "path": "Device.Users.User.3.Enable", - "data": "1", - "type": "xsd:boolean" - }, - { - "path": "Device.Users.User.3.UserID", - "data": "55", - "type": "xsd:unsignedInt" - }, - { - "path": "Device.Users.User.3.Username", - "data": "ftp", - "type": "xsd:string" - }, - { - "path": "Device.Users.User.3.Password", - "data": "", - "type": "xsd:string" - }, - { - "path": "Device.Users.User.3.RemoteAccessCapable", - "data": "0", - "type": "xsd:boolean" - }, - { - "path": "Device.Users.User.3.GroupParticipation", - "data": "Device.Users.Group.8", - "type": "xsd:string" - }, - { - "path": "Device.Users.User.3.RoleParticipation", - "data": "", - "type": "xsd:string" - }, - { - "path": "Device.Users.User.3.StaticUser", - "data": "1", - "type": "xsd:boolean" - }, - { - "path": "Device.Users.User.3.Language", - "data": "", - "type": "xsd:string" - }, - { - "path": "Device.Users.User.3.Shell", - "data": "", - "type": "xsd:string" - }, - { - "path": "Device.Users.Group.1.Alias", - "data": "cpe-1", - "type": "xsd:string" - }, - { - "path": "Device.Users.Group.1.Enable", - "data": "1", - "type": "xsd:boolean" - }, - { - "path": "Device.Users.Group.1.GroupID", - "data": "0", - "type": "xsd:unsignedInt" - }, - { - "path": "Device.Users.Group.1.Groupname", - "data": "root", - "type": "xsd:string" - }, - { - "path": "Device.Users.Group.1.RoleParticipation", - "data": "", - "type": "xsd:string" - }, - { - "path": "Device.Users.Group.1.StaticGroup", - "data": "1", - "type": "xsd:boolean" - }, - { - "path": "Device.Users.Group.2.Alias", - "data": "cpe-2", - "type": "xsd:string" - }, - { - "path": "Device.Users.Group.2.Enable", - "data": "1", - "type": "xsd:boolean" - }, - { - "path": "Device.Users.Group.2.GroupID", - "data": "1", - "type": "xsd:unsignedInt" - }, - { - "path": "Device.Users.Group.2.Groupname", - "data": "daemon", - "type": "xsd:string" - }, - { - "path": "Device.Users.Group.2.RoleParticipation", - "data": "", - "type": "xsd:string" - }, - { - "path": "Device.Users.Group.2.StaticGroup", - "data": "1", - "type": "xsd:boolean" - }, - { - "path": "Device.Users.Group.18.StaticGroup", - "data": "1", - "type": "xsd:boolean" - }, - { - "path": "Device.Users.SupportedShell.1.Alias", - "data": "cpe-1", - "type": "xsd:string" - }, - { - "path": "Device.Users.SupportedShell.1.Enable", - "data": "1", - "type": "xsd:boolean" - }, - { - "path": "Device.Users.SupportedShell.1.Name", - "data": "ash", - "type": "xsd:string" - } - ] -} -root@iopsys:~# -root@iopsys:~# ubus call bbfdm get '{"path":"Device.WiFi.SSID.*.SSID"}' -{ - "SSID": [ - { - "SSID": "iopsysWrt-44D43771B120" - }, - { - "SSID": "MAP-44D43771B120-BH-5GHz" - }, - { - "SSID": "iopsysWrt-44D43771B120" - }, - { - "SSID": "MAP-44D43771B120-BH-2.4GHz" - } - ] -} -root@iopsys:~# -root@iopsys:~# ubus call bbfdm get '{"path":"Device.WiFi.SSID.*.SSID", "optional":{"format":"raw"}}' -{ - "results": [ - { - "path": "Device.WiFi.SSID.1.SSID", - "data": "iopsysWrt-44D43771B120", - "type": "xsd:string" - }, - { - "path": "Device.WiFi.SSID.2.SSID", - "data": "MAP-44D43771B120-BH-5GHz", - "type": "xsd:string" - }, - { - "path": "Device.WiFi.SSID.3.SSID", - "data": "iopsysWrt-44D43771B120", - "type": "xsd:string" - }, - { - "path": "Device.WiFi.SSID.4.SSID", - "data": "MAP-44D43771B120-BH-2.4GHz", - "type": "xsd:string" - } - ] -} -root@iopsys:~# -root@iopsys:~# ubus call bbfdm get '{"path":"Device.WiFi.SSID.[BSSID==\"be:d4:37:71:b1:28\"].SSID"}' -{ - "SSID": [ - { - "SSID": "MAP-44D43771B120-BH-5GHz" - } - ] -} -root@iopsys:~# -root@iopsys:~# ubus call bbfdm get '{"path":"Device.IP.Interface.[Status==\"Up\"].IPv4Address.[AddressingType==\"DHCP\"].IPAddress"}' -{ - "Interface": [ - { - "IPv4Address": [ - { - "IPAddress": "10.100.1.201" - } - ] - } - ] -} -root@iopsys:~# -root@iopsys:~# ubus call bbfdm get '{"path":"Device.IP.Interface.[Status==\"Up\"].IPv4Address.[AddressingType==\"DHCP\"&&Status==\"Up\"]."}' -{ - "Interface": [ - { - "IPv4Address": [ - { - "Enable": true, - "Status": "Enabled", - "Alias": "cpe-1", - "IPAddress": "10.100.1.201", - "SubnetMask": "255.255.255.0", - "AddressingType": "DHCP" - } - ] - } - ] -} -root@iopsys:~# -root@iopsys:~# ubus call bbfdm get '{"path":"Device.IP.Interface.[Type==\"Normal\"&&Stats.PacketsSent<=500].IPv4Address.[AddressingType==\"DHCP\"].IPAddress"}' -{ - "Interface": [ - { - "IPv4Address": [ - { - "IPAddress": "10.100.1.201" - } - ] - } - ] -} -root@iopsys:~# -root@iopsys:~# ubus call bbfdm get '{"path": "Device.Firewall.Chain.1.Rule.[Description==\"Allow-Ping\"]."}' -{ - "Rule": [ - { - "Enable": true, - "Status": "Enabled", - "Order": 3, - "Alias": "cpe-3", - "Description": "Allow-Ping", - "Target": "Accept", - "Log": false, - "CreationDate": "0001-01-01T00:00:00Z", - "ExpiryDate": "9999-12-31T23:59:59Z", - "SourceInterface": "Device.IP.Interface.2", - "SourceAllInterfaces": false, - "DestInterface": "", - "DestAllInterfaces": false, - "IPVersion": 4, - "DestIP": "", - "DestMask": "", - "SourceIP": "", - "SourceMask": "", - "Protocol": 1, - "DestPort": -1, - "DestPortRangeMax": -1, - "SourcePort": -1, - "SourcePortRangeMax": -1 - } - ] -} -``` - -- For more info on the `bbfdm` ubus API see [link](../api/ubus/bbfdm.md#get) - -### Get multiple values -API to get values of multiple objects at once, object name must be provided in `paths` parameter array as below. - -```console -root@iopsys:~# ubus call bbfdm get '{"paths":["Device.Users.User.1.Username","Device.DeviceInfo.SerialNumber"], "optional": {"format":"raw"}}' -{ - "results": [ - { - "path": "Device.Users.User.1.Username", - "data": "root", - "type": "xsd:string" - }, - { - "path": "Device.DeviceInfo.SerialNumber", - "data": "Y0721140086", - "type": "xsd:string" - } - ] -} -``` - -### Set single value -API to set value to specific object, object name must be provided in `path` parameter and value to be set in `value` option. - -> Note: bbfdmd decides how to handle set method based on the `transaction_id` value. If the `transaction_id` value is different to `0`, it checks if the transaction is valid, then proceeds set operation. Otherwise, it creates a internal transaction before actually setting the value and after set operation it automatically commits the transaction. Please refer to `transaction` API for more details. - -```console -root@iopsys:~# ubus call bbfdm set '{"path":"Device.WiFi.SSID.1.SSID", "value":"test-2g"}' -{ - "results": [ - { - "path": "Device.WiFi.SSID.1.SSID", - "data": "1" - } - ] -} -root@iopsys:~# ubus call bbfdm set '{"path":"Device.WiFi.SSID.1.SSID", "value":"test-2g", "optional":{"transaction_id":12345}}' -{ - "results": [ - { - "path": "Device.WiFi.SSID.1.SSID", - "data": "1" - } - ] -} -root@iopsys:~# ubus call bbfdm get '{"path":"Device.WiFi.SSID.1.SSID"}' -{ - "SSID": "test-2g" -} -``` - -- For more info on the `bbfdm` ubus API see [link](../api/ubus/bbfdm.md#set) - -### Set multiple values -API to set value to specific object, object name must be provided in `path` object and parameter and its value to be set in `obj_path` table. - -> Note: bbfdmd decides how to handle set method based on the `transaction_id` value. If the `transaction_id` value is different to `0`, it checks if the transaction is valid, then proceeds set operation. Otherwise, it creates a internal transaction before actually setting the value and after set operation it automatically commits the transaction. Please refer to `transaction` API for more details. - -```console -root@iopsys:~# ubus call bbfdm set '{"path":"Device.WiFi.SSID.1.", "obj_path":{"Enable":"0", "SSID":"test-2g"}}' -{ - "results": [ - { - "path": "Device.WiFi.SSID.1.Enable", - "data": "1" - }, - { - "path": "Device.WiFi.SSID.1.SSID", - "data": "1" - } - ] -} -root@iopsys:~# ubus call bbfdm set '{"path":"Device.WiFi.SSID.1.", "obj_path":{"Enable":"0", "SSID":"test-2g"}, "optional":{"transaction_id":12345}}' -{ - "results": [ - { - "path": "Device.WiFi.SSID.1.Enable", - "data": "1" - }, - { - "path": "Device.WiFi.SSID.1.SSID", - "data": "1" - } - ] -} -root@iopsys:~# ubus call bbfdm get '{"paths":["Device.WiFi.SSID.1.Enable", "Device.WiFi.SSID.1.SSID"]}' -{ - "Enable": false, - "SSID": "test-2g" -} -root@iopsys:~# ubus call bbfdm set '{"path": "Device.Firewall.Chain.1.Rule.[Description==\"Allow-Ping\"].", "obj_path": {"Target": "Accept"}}' -{ - "results": [ - { - "path": "Device.Firewall.Chain.1.Rule.3.Target", - "data": "1" - } - ] -} -``` - -- For more info on the `bbfdm` ubus API see [link](../api/ubus/bbfdm.md#set) - -### Operate -API to run operate/diagnostics commands as defined in TR-369 - -```console -root@iopsys:~# ubus call bbfdm operate '{"command":"Device.IP.Diagnostics.IPPing()", "command_key":"ipping_test", "input":{"Host":"iopsys.eu"}}' -{ - "results": [ - { - "path": "Device.IP.Diagnostics.IPPing()", - "data": "ipping_test", - "output": [ - { - "Status": "Complete", - "IPAddressUsed": "10.100.1.122", - "SuccessCount": 3, - "FailureCount": 0, - "AverageResponseTime": 31, - "MinimumResponseTime": 30, - "MaximumResponseTime": 31, - "AverageResponseTimeDetailed": 31007, - "MinimumResponseTimeDetailed": 30957, - "MaximumResponseTimeDetailed": 31059 - } - ] - } - ] -} -root@iopsys:~# ubus call bbfdm operate '{"command":"Device.IP.Diagnostics.IPPing()", "command_key":"ipping_test", "input":{"Host":"iopsys.eu"}, "optional":{"format":"raw"}}' -{ - "results": [ - { - "path": "Device.IP.Diagnostics.IPPing()", - "data": "ipping_test", - "output": [ - { - "path": "Status", - "data": "Complete", - "type": "xsd:string" - }, - { - "path": "IPAddressUsed", - "data": "10.100.1.122", - "type": "xsd:string" - }, - { - "path": "SuccessCount", - "data": "3", - "type": "xsd:unsignedInt" - }, - { - "path": "FailureCount", - "data": "0", - "type": "xsd:unsignedInt" - } - ] - } - ] -} -root@iopsys:~# ubus call bbfdm operate '{"command":"Device.IP.Interface.2.Reset()"}' -{ - "results": [ - { - "path": "Device.IP.Interface.2.Reset()", - "data": "", - "output": [ - { - - } - ] - } - ] -} -root@iopsys:~# ubus call bbfdm operate '{"command":"Device.IP.Interface.2.Reset()", "optional":{"format":"raw"}}' -{ - "results": [ - { - "path": "Device.IP.Interface.2.Reset()", - "data": "", - "output": [ - - ] - } - ] -} -``` - -- For more info on the `bbfdm` ubus API see [link](../api/ubus/bbfdm.md#operate) - - -### Add object -API to add new objects in multi-instance object - -> Note: bbfdmd decides how to handle `add_object` method based on the `transaction_id` value. If the `transaction_id` value is different to `0`, it checks if the transaction is valid, then proceeds set operation. Otherwise, it creates a internal transaction before actually adding the object and after set operation it automatically commits the transaction. Please refer to `transaction` API for more details. - -```console -root@iopsys:~# ubus call bbfdm add '{"path":"Device.Users.User."}' -{ - "results": [ - { - "path": "Device.Users.User.", - "data": "14" - } - ] -} -root@iopsys:~# ubus call bbfdm add '{"path":"Device.Users.User.", "optional":{"transaction_id":12345}}' -{ - "results": [ - { - "path": "Device.Users.User.", - "data": "14" - } - ] -} -``` - -- For more info on the `bbfdm` ubus API see [link](../api/ubus/bbfdm.md#add) - -### Add object and setting its parameters -API to add new objects in multi-instance object - -> Note: bbfdmd decides how to handle `add_object` method based on the `transaction_id` value. If the `transaction_id` value is different to `0`, it checks if the transaction is valid, then proceeds set operation. Otherwise, it creates a internal transaction before actually adding the object and after add operation it automatically commits the transaction. Please refer to `transaction` API for more details. - -```console -root@iopsys:~# ubus call bbfdm add '{"path":"Device.Firewall.Chain.1.Rule.", "obj_path":{"Enable":"1", "Description":"rule for test"}}' -{ - "results": [ - { - "path": "Device.Firewall.Chain.1.Rule.", - "data": "12" - } - ], - "results": [ - { - "path": "Device.Firewall.Chain.1.Rule.12.Enable", - "data": "1" - }, - { - "path": "Device.Firewall.Chain.1.Rule.12.Description", - "data": "1" - } - ] -} -root@iopsys:~# ubus call bbfdm add '{"path":"Device.Firewall.Chain.1.Rule.", "obj_path":{"Enable":"1", "Description":"rule for test"}, "optional":{"transaction_id":12345}}' -{ - "results": [ - { - "path": "Device.Firewall.Chain.1.Rule.", - "data": "12" - } - ], - "results": [ - { - "path": "Device.Firewall.Chain.1.Rule.12.Enable", - "data": "1" - }, - { - "path": "Device.Firewall.Chain.1.Rule.12.Description", - "data": "1" - } - ] -} -root@iopsys:~# ubus call bbfdm get '{"paths":["Device.Firewall.Chain.1.Rule.12.Enable", "Device.Firewall.Chain.1.Rule.12.Description"]}' -{ - "Enable": true, - "Description": "rule for test" -} -``` - -- For more info on the `bbfdm` ubus API see [link](../api/ubus/bbfdm.md#add) - -### Delete single object -API to delete an existing object from multi-instance object - -> Note: bbfdmd decides how to handle `add_object` method based on the `transaction_id` value. If the `transaction_id` value is different to `0`, it checks if the transaction is valid, then proceeds set operation. Otherwise, it creates a internal transaction before actually deleting the object and after del operation it automatically commits the transaction. Please refer to `transaction` API for more details. - -```console -root@iopsys:~# ubus call bbfdm del '{"path":"Device.Firewall.Chain.1.Rule.12."}' -{ - "results": [ - { - "path": "Device.Firewall.Chain.1.Rule.12.", - "data": "1" - } - ] -} -root@iopsys:~# ubus call bbfdm del '{"path":"Device.Firewall.Chain.1.Rule.12.", "optional":{"transaction_id":12345}}' -{ - "results": [ - { - "path": "Device.Firewall.Chain.1.Rule.12.", - "data": "1" - } - ] -} -``` - -- For more info on the `bbfdm` ubus API see [link](../api/ubus/bbfdm.md#del) - -### Delete multiple objects -API to delete an existing object from multi-instance object - -> Note: bbfdmd decides how to handle `add_object` method based on the `transaction_id` value. If the `transaction_id` value is different to `0`, it checks if the transaction is valid, then proceeds set operation. Otherwise, it creates a internal transaction before actually deleting the object and after del operation it automatically commits the transaction. Please refer to `transaction` API for more details. - -```console -root@iopsys:~# ubus call bbfdm del '{"paths":["Device.Firewall.Chain.1.Rule.10.","Device.Firewall.Chain.1.Rule.11."]}' -{ - "results": [ - { - "path": "Device.Firewall.Chain.1.Rule.10.", - "data": "1" - }, - { - "path": "Device.Firewall.Chain.1.Rule.11.", - "data": "1" - } - ] -} -root@iopsys:~# ubus call bbfdm del '{"paths":["Device.Firewall.Chain.1.Rule.10.","Device.Firewall.Chain.1.Rule.11."], "optional":{"transaction_id":12345}}' -{ - "results": [ - { - "path": "Device.Firewall.Chain.1.Rule.12.", - "data": "1" - } - ] -} -``` - -- For more info on the `bbfdm` ubus API see [link](../api/ubus/bbfdm.md#del) - - -### Object names -API to get the available list of object names which is available only with `cwmp` proto. - -```console -root@iopsys:~# ubus call bbfdm schema '{"path":"Device.DeviceInfo.SerialNumber", "optional":{"proto":"cwmp"}}' -{ - "results": [ - { - "path": "Device.DeviceInfo.SerialNumber", - "data": "0", - "type": "xsd:string" - } - ] -} -root@iopsys:~# -root@iopsys:~# ubus call bbfdm schema '{"path":"Device.Users.", "optional":{"proto":"cwmp"}}' -{ - "results": [ - { - "path": "Device.Users.", - "data": "0", - "type": "xsd:object" - }, - { - "path": "Device.Users.UserNumberOfEntries", - "data": "0", - "type": "xsd:unsignedInt" - }, - { - "path": "Device.Users.GroupNumberOfEntries", - "data": "0", - "type": "xsd:unsignedInt" - }, - { - "path": "Device.Users.RoleNumberOfEntries", - "data": "0", - "type": "xsd:unsignedInt" - }, - { - "path": "Device.Users.SupportedShellNumberOfEntries", - "data": "0", - "type": "xsd:unsignedInt" - }, - { - "path": "Device.Users.User.", - "data": "1", - "type": "xsd:object" - }, - { - "path": "Device.Users.User.1.", - "data": "1", - "type": "xsd:object" - }, - { - "path": "Device.Users.User.1.Alias", - "data": "1", - "type": "xsd:string" - }, - { - "path": "Device.Users.User.1.Enable", - "data": "1", - "type": "xsd:boolean" - }, - { - "path": "Device.Users.User.1.UserID", - "data": "0", - "type": "xsd:unsignedInt" - }, - { - "path": "Device.Users.User.1.Username", - "data": "1", - "type": "xsd:string" - }, - { - "path": "Device.Users.User.1.Password", - "data": "1", - "type": "xsd:string" - } - ] -} -root@iopsys:~# -``` - -### Instances -API to get the available instances of an multi-instance object. USP Instances method returns the registered instances. - -```console -root@iopsys:~# ubus call bbfdm instances '{"path":"Device.IP.Interface."}' -{ - "results": [ - { - "path": "Device.IP.Interface.1" - }, - { - "path": "Device.IP.Interface.1.IPv4Address.1" - }, - { - "path": "Device.IP.Interface.1.IPv6Address.1" - }, - { - "path": "Device.IP.Interface.1.IPv6Address.2" - }, - { - "path": "Device.IP.Interface.1.IPv6Prefix.1" - }, - { - "path": "Device.IP.Interface.2" - } - ] -} -``` - -- For more info on the `bbfdm` ubus API see [link](../api/ubus/bbfdm.md#instances) - -### schema -API to dump all registered schema paths - -```console -root@iopsys:~# ubus call bbfdm schema '{"path":"Device.WiFi.", "optional":{"proto":"usp"}}' -{ - "results": [ - { - "path": "Device.WiFi.RadioNumberOfEntries", - "data": "0", - "type": "xsd:unsignedInt" - }, - { - "path": "Device.WiFi.SSIDNumberOfEntries", - "data": "0", - "type": "xsd:unsignedInt" - }, - { - "path": "Device.WiFi.AccessPointNumberOfEntries", - "data": "0", - "type": "xsd:unsignedInt" - }, - { - "path": "Device.WiFi.EndPointNumberOfEntries", - "data": "0", - "type": "xsd:unsignedInt" - }, - { - "path": "Device.WiFi.Reset()", - "type": "xsd:command", - "data": "sync" - }, - { - "path": "Device.WiFi.NeighboringWiFiDiagnostic()", - "type": "xsd:command", - "data": "async", - "output": [ - { - "path": "Status" - }, - { - "path": "Result.{i}.Radio" - }, - { - "path": "Result.{i}.SSID" - }, - { - "path": "Result.{i}.BSSID" - }, - { - "path": "Result.{i}.Mode" - }, - { - "path": "Result.{i}.Channel" - }, - { - "path": "Result.{i}.SignalStrength" - }, - { - "path": "Result.{i}.SecurityModeEnabled" - }, - { - "path": "Result.{i}.EncryptionMode" - }, - { - "path": "Result.{i}.OperatingFrequencyBand" - }, - { - "path": "Result.{i}.SupportedStandards" - }, - { - "path": "Result.{i}.OperatingStandards" - }, - { - "path": "Result.{i}.OperatingChannelBandwidth" - }, - { - "path": "Result.{i}.BeaconPeriod" - }, - { - "path": "Result.{i}.Noise" - }, - { - "path": "Result.{i}.BasicDataTransferRates" - }, - { - "path": "Result.{i}.SupportedDataTransferRates" - }, - { - "path": "Result.{i}.DTIMPeriod" - } - ] - } - ] -} -``` - -### Transaction start -To support the `allow_partial` and `required` parameters in Add/Del/Set operation as defined in TR-369, transaction_* APIs introduced. -It basically works around data-model objects which has dependent uci config files for each CUD operation. -API to start a transaction for add/del/set operations - - -```console -root@iopsys:~# ubus call bbfdm transaction '{"cmd":"start"}' -{ - "status": true, - "transaction_id": 1727398631 -} -``` - -It's sometime required to have a per transaction timeout, which can be defined along with transaction_start -```bash -root@4949e4da3d27:~# ubus call bbfdm transaction '{"cmd":"start", "timeout":30}' -{ - "status": true, - "transaction_id": 2124763996 -} - -``` -> Note: max_timeout is time in second, its an optional input argument if not provided, uci default (bbfdm.bbfdmd.transaction_timeout) is used which is defined in seconds -> If uci option bbfdm.bbfdmd.transaction_timeout not set than a default 10 second timeout is used for the transactions. - -### Get status of a transaction -API to get details and check status of a transaction id - -```console -root@iopsys:~# ubus call bbfdm transaction '{"cmd":"status", "optional":{"transaction_id":439041413}}' -{ - "status": "on-going", - "remaining_time": 17 -} -root@iopsys:~# -root@iopsys:~# ubus call bbfdm transaction '{"cmd":"status", "optional":{"transaction_id":439041413}}' -{ - "status": "not-exists" -} -root@iopsys:~# -``` - -### Transaction commit -API to commit an on-going transaction, on calling this api, uci changes shall be committed and required services shall be restarted. - -```console -root@iopsys:~# ubus call bbfdm transaction '{"cmd":"commit", "optional":{"transaction_id":439041413}}' -{ - "updated_services": [ - "mapcontroller", - "wireless" - ], - "status": true -} -``` - -### Transaction abort -API to abort an on-going transaction, on calling this api, staged changes in uci shall be reverted to earlier values. - -```console -root@iopsys:~# ubus call bbfdm transaction '{"cmd":"abort", "optional":{"transaction_id":1695754826}}' -{ - "updated_services": [ - "mapcontroller", - "wireless" - ], - "status": true -} -``` diff --git a/docs/guide/bbfdmd_ubus_parallel_call.md b/docs/guide/bbfdmd_ubus_parallel_call.md deleted file mode 100644 index 7ef4e228..00000000 --- a/docs/guide/bbfdmd_ubus_parallel_call.md +++ /dev/null @@ -1,20 +0,0 @@ -# Parallel UBUS calls - -All `operate` operation and `get` operation with a depth up to 'BBF_SUBPROCESS_DEPTH(2)' -runs in a parallel subprocess to avoid blocking the next call. - -```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:~# -``` - diff --git a/docs/guide/libbbfdm-api.md b/docs/guide/libbbfdm-api.md new file mode 100644 index 00000000..9e0c5877 --- /dev/null +++ b/docs/guide/libbbfdm-api.md @@ -0,0 +1,196 @@ +# API guide and usages + +`libbbfdm-api` 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) + +Following is the list of APIs used by bbfdmd for tree traversal: + +### bbf_entry_method + +used to read the data model based on the input given + +``` +int bbf_entry_method(struct dmctx *ctx, int cmd) + +inputs + struct dmctx *ctx + pointer to struct dmctx strunture. The list of parameter will be updated in ctx.list_parameter. each node in the list is of type + struct dm_parameter which contains char *name, char *data, char *type and char *additional_data; + the content of fields are updated based on the cmd and are as follows- + cmd | Name | Type | Data | Addtional Data | + |------------- |------------- |------------- |------------ |--------------------- | + |BBF_GET_VALUE |Parameter |$ref(type) |Value | NA | + |BBF_GET_NAME |Parameter |$ref(type) |writable(0/1) | NA | + |BBF_SET_VALUE |path | NA | NA | NA | + |BBF_ADD_OBJECT |path | NA | NA | NA | + |BBF_DEL_OBJECT |path | NA | NA | NA | + |BBF_OPERATE |path | NA | NA | NA | + |BBF_SCHEMA |paramter ||$ref(type) |writable(0/1) |unique keys | + |BBF_INSTANCES |parameter | NA |NA |NA | + |BBF_EVENT |path | NA | NA | NA | + + int cmd + command to API to tell how the data model is to be read, possible values are + BBF_GET_VALUE - Read the values of the parameters from data model + BBF_GET_NAME - Read the names of the parameters from data model + BBF_SET_VALUE - Set value of specified parameters in the data model + BBF_ADD_OBJECT - Add object in a multi instance parameter in the data model + BBF_DEL_OBJECT - Delete object from a multi instance parameter in the data model + BBF_OPERATE - execute the specified command + BBF_SCHEMA - Read all the parameter type parameter from data model. + BBF_INSTANCES - Read all the instance of multi instance parameter from data model. + BBF_EVENT - execute the specified event + +return + int fault + contains the fault code if API is not able to read the data model. returns 0 on success. +``` + +### bbf_ctx_init + +This method is used to initialize the dmctx structure object to read the data model. + +``` +void bbf_ctx_init(struct dmctx *ctx, DMOBJ *tEntryObj); +inputs + struct dmctx *ctx + pointer to struct dmctx strunture to be initialized. + +return + None +``` + +### bbf_ctx_init_sub + +This method is an extension of bbf_ctx_init method. only difference it only intializes dmctx structure object and does not intializes other resources used in reading data model + +``` +void bbf_ctx_init_sub(struct dmctx *ctx, DMOBJ *tEntryObj) +inputs + struct dmctx *ctx + pointer to struct dmctx strunture to be initialized. + +return + None +``` + + +### bbf_ctx_clean + +This method is used to free the dmctx structure object and other resources post reading the data model. + +``` +void bbf_ctx_clean(struct dmctx *ctx) + +input + struct dmctx *ctx + pointer to struct dmctx strunture to be freed. + +return + None +``` + +### bbf_ctx_clean_sub + +This method is an extension of bbf_ctx_clean method. only difference is it frees the dmctx structure and does not free other resources used in reading data model + +``` +void bbf_ctx_clean_sub(struct dmctx *ctx) + +input + struct dmctx *ctx + pointer to struct dmctx strunture to be freed. + +return + None +``` + +### bbf_entry_restart_services + +This method is used to restart the state of data model whenever its state is changed + +``` +void bbf_entry_restart_services(struct blob_buf *bb, bool restart_services) + +input + struct blob_buf *bb + pointer to the struct blob_buf object. contains all the packages updated. + + bool restart_services + if true packages will be updated through ubus call. + if false packages will be updated through uci. + +return + None +``` +### bbf_entry_revert_changes + +This method is used to revert the changes whenever its state is changed + +``` +void bbf_entry_revert_changes(struct blob_buf *bb) + +input + struct blob_buf *bb + pointer to the struct blob_buf object. contains all the packages updated. + +return + None +``` + +# 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. + +Following table has APIs/datatypes which are now deprecated: + +| Type | Deprecated API | New API | Comment | +| -------- | ------------------------- | ---------------------------- | ------- | +| function | `bbf_get_reference_param` | `bbfdm_get_references` | Replaced with a generic API that is accessible for both internal (bbfdm core) and external (microservices) data models | +| function | `bbf_get_reference_args` | `bbfdm_get_reference_linker` | Replaced with a generic API that is accessible for both internal (bbfdm core) and external (microservices) data models | +| 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: + +| Type | Removed API | New API | Comment | +| -------- | ---------------------------------- | ------------------------------------ | -------------------------------------- | +| function | `dm_validate_string` | `bbfdm_validate_string` | To support fault_msg in case of errors | +| function | `bbf_validate_string` | `bbfdm_validate_string` | To support fault_msg in case of errors | +| function | `bbf_validate_boolean` | `bbfdm_validate_boolean` | To support fault_msg in case of errors | +| function | `bbf_validate_unsignedInt` | `bbfdm_validate_unsignedInt` | To support fault_msg in case of errors | +| function | `bbf_validate_int` | `bbfdm_validate_int` | To support fault_msg in case of errors | +| function | `bbf_validate_unsignedLong` | `bbfdm_validate_unsignedLong` | To support fault_msg in case of errors | +| function | `bbf_validate_long` | `bbfdm_validate_long` | To support fault_msg in case of errors | +| function | `bbf_validate_dateTime` | `bbfdm_validate_dateTime` | To support fault_msg in case of errors | +| function | `bbf_validate_hexBinary` | `bbfdm_validate_hexBinary` | To support fault_msg in case of errors | +| function | `bbf_validate_string_list` | `bbfdm_validate_string_list` | To support fault_msg in case of errors | +| function | `bbf_validate_unsignedInt_list` | `bbfdm_validate_unsignedInt_list` | To support fault_msg in case of errors | +| function | `bbf_validate_int_list` | `bbfdm_validate_int_list` | To support fault_msg in case of errors | +| function | `bbf_validate_unsignedLong_list` | `bbfdm_validate_unsignedLong_list` | To support fault_msg in case of errors | +| function | `bbf_validate_long_list` | `bbfdm_validate_long_list` | To support fault_msg in case of errors | +| function | `bbf_validate_hexBinary_list` | `bbfdm_validate_hexBinary_list` | To support fault_msg in case of errors | +| function | `dm_validate_boolean` | `bbfdm_validate_boolean` | To support fault_msg in case of errors | +| function | `dm_validate_unsignedInt` | `bbfdm_validate_unsignedInt` | To support fault_msg in case of errors | +| function | `dm_validate_int` | `bbfdm_validate_int` | To support fault_msg in case of errors | +| function | `dm_validate_unsignedLong` | `bbfdm_validate_unsignedLong` | To support fault_msg in case of errors | +| function | `dm_validate_long` | `bbfdm_validate_long` | To support fault_msg in case of errors | +| function | `dm_validate_dateTime` | `bbfdm_validate_dateTime` | To support fault_msg in case of errors | +| function | `dm_validate_hexBinary` | `bbfdm_validate_hexBinary` | To support fault_msg in case of errors | +| function | `dm_validate_string_list` | `bbfdm_validate_string_list` | To support fault_msg in case of errors | +| function | `dm_validate_unsignedInt_list` | `bbfdm_validate_unsignedInt_list` | To support fault_msg in case of errors | +| function | `dm_validate_int_list` | `bbfdm_validate_int_list` | To support fault_msg in case of errors | +| function | `dm_validate_unsignedLong_list` | `bbfdm_validate_unsignedLong_list` | To support fault_msg in case of errors | +| function | `dm_validate_long_list` | `bbfdm_validate_long_list` | To support fault_msg in case of errors | +| function | `dm_validate_hexBinary_list` | `bbfdm_validate_hexBinary_list` | To support fault_msg in case of errors | +| function | `dm_entry_validate_allowed_objects`| `dm_validate_allowed_objects` | Replaced with a generic API that is accessible for both internal (bbfdm core) and external (microservices) data models | +| function | `dm_entry_validate_external_linker_allowed_objects` | `dm_validate_allowed_objects` | Replaced with a generic API that is accessible for both internal (bbfdm core) and external (microservices) data models | +| function | `adm_entry_get_linker_param` | | Removed, no more required | +| function | `adm_entry_get_linker_value` | | Removed, no more required | +| enum | `CMD_SUCCESS` | | Removed, no more required | +| enum | `CMD_INVALID_ARGUMENTS` | | Removed, no more required | +| enum | `CMD_FAIL` | | Removed, no more required | +| enum | `CMD_NOT_FOUND` | | Removed, no more required | +| enum | `__STATUS_MAX` | | Removed, no more required | + diff --git a/docs/guide/libbbfdm-api_datamodel_as_microservice.md b/docs/guide/libbbfdm-api_datamodel_as_microservice.md deleted file mode 100644 index bb8f45eb..00000000 --- a/docs/guide/libbbfdm-api_datamodel_as_microservice.md +++ /dev/null @@ -1,134 +0,0 @@ -# Datamodel additions (DotSO Plugin/ JSON Plugin/ Micro-Service) - -It is often required by customers to have/implement some datamodel parameters which is not available in bbfdm, `bbfdm` provides four ways to extend the existing datamodel parameters. - -- Using [JSON Plugin](./json_plugin_v1.md) -- Using [DotSO Plugin](./bbfdm_dm_integration.md) -- With bbfdm micro-service -- [Individual datamodel daemon](https://dev.iopsys.eu/voice/tr104) - -Out of all the supported method, each have its own pro and cons: - -## JSON Plugins -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 - - In-tree datamodel references not supported - - Invalid plugin syntax might cause segfault on main bbfdmd service, result in complete cwmp/usp service down - - Make the main tree bigger, which result into slow service time - -## DotSO Plugin -Pro: - - Similar to adding in the core - - Support complex mapping and data sharing between nodes - - All core operations supported - -Con: - - Moderate maintenance (Change in libbbfdm-api requires adaptation/alignment) - - Any segfault on plugin might teardown main bbfdmd service, result in complete cwmp/usp service down - - Make the main tree bigger, which result into slow service time - -## BBFDM micro-service -Pro: - - Creates a sub datamodel tree and registers to main datamodel tree - - Can be used with existing DotSO and JSON Plugins - - Faults in plugins only limited to micro-service, main tree won't gets affected - -Con: - - Currently references to out side tree nodes not supported - - Maintenance cost depends on JSON or DotSO plugin selection - -## Individual daemon to run micro-service -It has same pro and cons as of running the plugin with micro-service, with a added benefit of low maintenance as all the dependency embedded in single binary. - -## Workflow of Individual daemon and micro-service -daemon started by the init script, it adds its own ubus objects based on input and wait for parent/master ubus object, once master ubus object available, it registers self with the main tree. - -`icwmp` and `obuspa` gets the datamodel from main tree which is provided by `bbfdm` daemon, so no change required in either cwmp and obuspa. - -## Summary -In plugins approach, the 3rd party datamodel gets attached to main bbfdm process, which further increases nodes in main datamodel tree, which overtime become a huge tree, results in slower turn around service time for the APIs. - -Also with plugins, since its part of main process, any unhandled fault result in segfault in main bbfdmd process, which takes down the whole tree along with it, resulting in complete failure from cwmp and USP, with micro-services plugins runs as an individual processes, so impact of fault limited to its own process only. - -Micro-service approach, disintegrate the plugins further and run them as individual daemons with the help of "bbfdmd" "-m" command line options. - -## How to switch to micro-service model -It's a three step process, if DotSO or JSON plugin already present, if not refer to the plugins document. - -1. Install the DotSO/JSON plugin to non-bbf plugin location -2. Create an json file with required input parameters, like below - -```json -{ - "daemon": { - "config": { - "loglevel": "1" - }, - "input": { - "type": "JSON", // JSON or DotSO - "name": "/etc/bulkdata/bulkdata.json" // Path of the plugin - }, - "output": { - "type": "UBUS", - "parent_dm": "Device.", // Parent tree to attach the plugin - "object": "BulkData", // Name of the object - "root_obj": "bbfdm" // Name of the root tree ubus object which is bbfdm - } - } -} -``` - -3. Place this json file in micro-service(`/etc/bbfdm/micro_services`) directory - -```bash -$ cat /etc/bbfdm/micro_services/bulkdata.json -{ - "daemon": { - "config": { - "loglevel": "1" - }, - "input": { - "type": "JSON", - "name": "/etc/bulkdata/bulkdata.json" - }, - "output": { - "type": "UBUS", - "parent_dm": "Device.", - "object": "BulkData", - "root_obj": "bbfdm" - } - } -} -``` - -Which then gets started by `bbfdmd` init script. - -## When to switch to micro-service model -There are few parameters which can help in answer this query, -1. If a plugin add significantly huge amount of nodes to main tree -2. If the service known to miss-behave and cause faults -3. If a plugin add a service with no/less dependency on other datamodel parameters - -## DotSO Plugins examples - - [STUN](https://dev.iopsys.eu/bbf/stunc.git) - - [UDPEcho](https://dev.iopsys.eu/bbf/udpecho.git) - - [SoftwareModule](https://dev.iopsys.eu/bbf/swmodd.git) - - [XMPP](https://dev.iopsys.eu/bbf/xmpp.git) - - [TWAMP](https://dev.iopsys.eu/bbf/twamp-light.git) - - [Usermngr](https://dev.iopsys.eu/bbf/usermngr.git) - - [ManagementServer](https://dev.iopsys.eu/bbf/icwmp.git) - -## JSON Plugin example - - [URLFilter](https://dev.iopsys.eu/feed/iopsys/-/blob/devel/urlfilter/files/etc/bbfdm/json/urlfilter.json) - - [XPON](https://dev.iopsys.eu/feed/iopsys/-/blob/devel/ponmngr/files/etc/bbfdm/json/xpon.json) - -## Micro service example - - [Bulkdata](https://dev.iopsys.eu/feed/iopsys/-/commit/8bdfd3ea51a81941ee9c53a46a66cf6c0f6eb88f) - - [PeriodicStats](https://dev.iopsys.eu/feed/iopsys/-/commit/66163d394586b953b8f891f91afb1677df29403a) - -## Individual daemons - - [TR104](https://dev.iopsys.eu/feed/iopsys/-/commit/7160fadf5607fcc785fd13e41eac402da6164280) diff --git a/docs/guide/libbbfdm-api_dynamic_dm.md b/docs/guide/libbbfdm-api_dynamic_dm.md deleted file mode 100644 index 4feb50dc..00000000 --- a/docs/guide/libbbfdm-api_dynamic_dm.md +++ /dev/null @@ -1,425 +0,0 @@ -# BBFDM Dynamic Object/Parameter/Operate/Event - -`bbfdm` library allows all applications installed on the box to import its own Data Model parameters at run time in two formats: - -- **Shared library** - -- **JSON files** - -## 1. Shared library via external package - -The application should bring its shared library under **'/usr/share/bbfdm/plugins'** path that contains the sub tree of **Objects/Parameters** and the related functions **Get/Set/Add/Delete/Operate**. The new added objects, parameters and operates will be automatically shown by icwmpd and bbfdmd/obuspa. - -Each library should contains the Root table: **“tDynamicObj”** - - -### DynamicObject definition - -The “tDynamicObj” table contains entries of **DM_MAP_OBJ** structure. - -The **DM_MAP_OBJ** structure contains three arguments: - -| Argument | Description | -| ---------------- | ------------------------------------------------------------------------------------------------------------- | -| `parentobj` | A string of the parent object name. Example “Device.IP.Diagnostics.”, “Device.DeviceInfo”, “Device.WiFi.Radio.” | -| `nextobject` | Pointer to a **DMOBJ** array which contains a list of the child objects | -| `parameter` | Pointer to a **DMLEAF** array which contains a list of the child parameters | - - -For the other tables, they are defined in the same way as the Object and Parameter definition described above. - -> Note1: Shared library can only add vendor or standard objects that are not implemented by `libbbfdm` - -> Note2: Shared library is not allowed to overwrite objects/parameters - -- For more examples on the external packages, you can see these links: [BulkData](https://dev.iopsys.eu/bbf/bulkdata/-/blob/master/datamodel.c), [XMPP](https://dev.iopsys.eu/bbf/xmppc/-/blob/master/datamodel.c) - -### 2. JSON File via external package - -The application should bring its JSON file under **'/etc/bbfdm/json/'** path with **UCI** and **UBUS** mappings. The new added parameters will be automatically shown by icwmpd and bbfdmd/obuspa. - -#### Some examples on JSON Definition - -**1. Object without instance:** - -```bash -"Device.CWMP.": { - "type": "object", - "protocols": [ - "cwmp", - "usp" - ], - "array": false, - "access": false -} -``` - -**2. Object with instance:** - -- **UCI command:** uci show wireless | grep wifi-device - -```bash -"Device.X_IOPSYS_EU_Radio.{i}.": { - "type": "object", - "protocols": [ - "cwmp", - "usp" - ], - "array": true, - "access": true, - "mapping": { - "type": "uci", - "uci": { - "file": "wireless", - "section": { - "type": "wifi-device" - }, - "dmmapfile": "dmmap_wireless" - } - } -} -``` - -- **UBUS command:** ubus call dsl status | jsonfilter -e @.line - -```bash -"Device.DSL.Line.{i}.": { - "type": "object", - "protocols": [ - "cwmp", - "usp" - ], - "array": true, - "access": false, - "mapping": { - "type": "ubus", - "ubus": { - "object": "dsl", - "method": "status", - "args": {}, - "key": "line" - } - } -} -``` - -**3. Parameter under object with instance:** - -- **UCI option command:** uci get wireless.@wifi-device[0].country - -- **@i:** is the number of instance object - -```bash -"Country": { - "type": "string", - "protocols": [ - "cwmp", - "usp" - ], - "read": true, - "write": true, - "mapping": [ - { - "type" : "uci", - "uci" : { - "file" : "wireless", - "section" : { - "type": "wifi-device", - "index": "@i-1" - }, - "option" : { - "name" : "country" - } - } - } - ] -} -``` - -- **UCI list command:** uci get urlfilter.@profile[0].whitelist_url - -- **@i:** is the number of instance object - -```bash -"WhitelistURL": { - "type": "string", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "list": { - "datatype": "string" - }, - "mapping": [ - { - "type": "uci", - "uci": { - "file": "urlfilter", - "section": { - "type": "profile", - "index": "@i-1" - }, - "list": { - "name": "whitelist_url" - } - } - } - ] -} -``` - - -- **UBUS command:** ubus call wifi status | jsonfilter -e @.radios[0].noise - -- **@i:** is the number of instance object - -```bash -"Noise": { - "type": "int", - "protocols": [ - "cwmp", - "usp" - ], - "read": true, - "write": false, - "mapping": [ - { - "type" : "ubus", - "ubus" : { - "object" : "wifi", - "method" : "status", - "args" : {}, - "key" : "radios[@i-1].noise" - } - } - ] -} -``` - -**4. Parameter without instance:** - -- **UCI option command:** uci get cwmp.cpe.userid - -```bash -"Username": { - "type": "string", - "protocols": [ - "cwmp", - "usp" - ], - "read": true, - "write": true, - "mapping": [ - { - "type" : "uci", - "uci" : { - "file" : "cwmp", - "section" : { - "type": "cwmp", - "name": "cpe" - }, - "option" : { - "name" : "userid" - } - } - } - ] -} -``` - -- **UCI list command:** uci get urlfilter.globals.blacklist_url - -- **@i:** is the number of instance object - -```bash -"BlacklistURL": { - "type": "string", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "list": { - "datatype": "string" - }, - "mapping": [ - { - "type": "uci", - "uci": { - "file": "urlfilter", - "section": { - "name": "globals" - }, - "list": { - "name": "blacklist_url" - } - } - } - ] -} -``` - -- **UBUS command:** ubus call system info | jsonfilter -e @.uptime - -```bash -"Uptime": { - "type": "unsignedInt", - "protocols": [ - "cwmp", - "usp" - ], - "read": true, - "write": false, - "mapping": [ - { - "type" : "ubus", - "ubus" : { - "object" : "system", - "method" : "info", - "args" : {}, - "key" : "uptime" - } - } - ] -} -``` - -- **UBUS command:** ubus call system info | jsonfilter -e @.memory.total - -```bash -"Total": { - "type": "unsignedInt", - "protocols": [ - "cwmp", - "usp" - ], - "read": true, - "write": false, - "mapping": [ - { - "type" : "ubus", - "ubus" : { - "object" : "system", - "method" : "info", - "args" : {}, - "key" : "memory.total" - } - } - ] -} -``` - -**5. Parameter to map another data model Object:** - -- **UCI option command:** uci get urlfilter.@filter[0].profile - -- **linker_obj** is the path name of an object that is stacked immediately below this object - -```bash -"Profile": { - "type": "string", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "mapping": [ - { - "type": "uci", - "uci": { - "file": "urlfilter", - "section": { - "type": "filter", - "index": "@i-1" - }, - "option": { - "name": "profile" - } - }, - "linker_obj": "Device.{BBF_VENDOR_PREFIX}URLFilter.Profile.*.Name" - } - ] -} -``` - -**6. Object with Event and Operate command:** - -```bash -{ - "Device.X_IOPSYS_Test.": { - "type": "object", - "protocols": [ - "cwmp", - "usp" - ], - "array": false, - "access": false, - "Push!": { - "type": "event", - "protocols": [ - "usp" - ], - "data": { - "type": "string", - "read": true, - "write": true, - "protocols": [ - "usp" - ] - } - }, - "Status()": { - "type": "command", - "async": true, - "protocols": [ - "usp" - ], - "input": { - "Option": { - "type": "string", - "read": "true", - "write": "true", - "protocols": [ - "usp" - ] - } - }, - "output": { - "Result": { - "type": "string", - "read": "true", - "write": "false", - "protocols": [ - "usp" - ] - } - }, - "mapping": [ - { - "type": "ubus", - "ubus": { - "object": "test", - "method": "status" - } - } - ] - } - } -} -``` - -> Note1: JSON File can only add vendor or standard objects that are not implemented by `libbbfdm` - -> Note2: JSON File is not allowed to overwrite objects/parameters - -> Note3: Set, Add, Delete methods are only allowed for uci mapping. therefore for ubus mapping, only Get method is authorized - -> Note4: Each object definition in JSON file must begin with "Device." and should have the full parent path if it is under another object - -- For more examples on JSON files, you can see these links: [X_IOPSYS_EU_MCPD](https://dev.iopsys.eu/feed/broadcom/-/blob/devel/mcpd/files/etc/bbfdm/json/X_IOPSYS_EU_MCPD.json), [X_IOPSYS_EU_Dropbear](../../test/files/etc/bbfdm/json/X_IOPSYS_EU_Dropbear.json), [X_IOPSYS_EU_TEST](../../test/files/etc/bbfdm/json/X_IOPSYS_EU_TEST.json) - - diff --git a/docs/guide/libbbfdm-api_json_plugin_v2.md b/docs/guide/libbbfdm-api_json_plugin_v2.md deleted file mode 100644 index bcdb5f86..00000000 --- a/docs/guide/libbbfdm-api_json_plugin_v2.md +++ /dev/null @@ -1,97 +0,0 @@ -# JSON Plugin Version 2 - -The purpose of this document is to describe the new features supported by JSON Plugin V2. - -JSON Plugin Version 2 introduces enhancements to the previous versions by providing increased flexibility in extending, overwriting, and excluding objects/parameters/commands/events from the core data model. - -## How It Works - -To illustrate how the new features work, let's consider the following example JSON Plugin: - -```json -{ - "json_plugin_version": 2, - "Device.WiFi.AccessPoint.{i}.Security.": { - "type": "object", - "protocols": [ - "cwmp", - "usp" - ], - "access": false, - "array": false, - "{BBF_VENDOR_PREFIX}KeyPassphrase": { - "type": "string", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "datatype": "string", - "mapping": [ - { - "data": "@Parent", - "type": "uci_sec", - "key": "key" - } - ] - }, - "WEPKey": { - "type": "string", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "datatype": "string", - "mapping": [ - { - "data": "@Parent", - "type": "uci_sec", - "key": "wek_key" - } - ] - }, - "SAEPassphrase": { - "type": "string", - "read": true, - "write": false, - "protocols": [ - "none" - ] - } - } -} -``` - -The JSON Plugin V2 operates by parsing the JSON file. Then it checks the parent top object, which in this example is `Device.WiFi.AccessPoint.{i}.Security`. - - - If this object exists in the core data model, the plugin proceeds to examine the next each subsequent level to determine the necessary action for each JSON object. - - - If the object does not exist in the core data model, it is extended. - - If the object exists, it is either overwritten or excluded, depending on the defined protocols. If the protocols array is defined as 'none', the object is excluded. - - - If the parent top object does not exist in the core data model, the plugin follows the old behavior defined in JSON Plugin V0 and V1, which is extending the core data model. - -Examples - - - Device.WiFi.AccessPoint.{i}.Security.X_IOPSYS_EU_KeyPassphrase: This parameter will be extended to the core data model since it does not exist. - - Device.WiFi.AccessPoint.{i}.Security.WEPKey: This parameter will be overwritten in the core data model since it already exists. - - Device.WiFi.AccessPoint.{i}.Security.SAEPassphrase: This parameter will be excluded from the core data model since it exists, but the new protocol defined is `none`. - -## Important Notes - -> Note1: To utilize the functionalities described, ensure that JSON version 2 is specified in the plugin by `json_plugin_version` option. - -> Note2: When extending a multiple-instance object, align the passed data from the browse function to children (LEAF) by keeping it `(struct uci_section *)data` pointer in case of the `type` is `uci_sec` or `(json_object *)data` pointer in case of the `type` is `json`. - -> Note3: The mapping format used by JSON Plugin V2 follows the format of version 1. Ensure that all mappings are aligned with JSON Plugin V1 specifications. - -> Note4: Additional examples for each feature can be found in the following links:[Extend](../../test/vendor_test/test_extend.json), [Overwrite](../../test/vendor_test/test_overwrite.json), and [Exclude](../../test/vendor_test/test_exclude.json). - -## Features Supported with JSON Plugin V2 - - - Allow extending the core tree with simple mappings based on the data passed from the parent object. - - Allow overwriting an existing object, parameter, command, or event from the core tree. - - Allow excluding an existing object, parameter, command, or event from the core tree. diff --git a/docs/guide/libbbfdm-api_migrate_deprecated_removed_api.md b/docs/guide/libbbfdm-api_migrate_deprecated_removed_api.md deleted file mode 100644 index 53dc5e27..00000000 --- a/docs/guide/libbbfdm-api_migrate_deprecated_removed_api.md +++ /dev/null @@ -1,55 +0,0 @@ -# Migration of 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. - -Following table has deprecated and new APIs, datatypes: - -| Type | Deprecated API | New API | Comment | -| ---- | -------------- | ------- | ------- | -| function | `int bbf_get_reference_param(char *path, char *key_name, char *key_value, char **value)` | `int bbfdm_get_references(struct dmctx *ctx, int match_action, const char *base_path, char *key_name, char *key_value, char *out, size_t out_len)` | Replaced with a generic API that is accessible for both internal (bbfdm core) and external (microservices) data models | -| function | `int bbf_get_reference_args(char *value, struct dm_reference *reference_args)` | `int bbfdm_get_reference_linker(struct dmctx *ctx, char *reference_path, struct dm_reference *reference_args)` | Replaced with a generic API that is accessible for both internal (bbfdm core) and external (microservices) data models | -| stucture | `struct dmmap_dup` | `structure dm_data` | Replaced to support the extension for Obj/Param/Operate using JSON plugin | - - -Following table has removed and new APIs, datatypes: - -| Type | Removed API | New API | Comment | -| ---- | -------------- | ------- | ------- | -| function | `dm_validate_string(char *value, int min_length, int max_length, char *enumeration[], char *pattern[])` | `int bbfdm_validate_string(struct dmctx *ctx, char *value, int min_length, int max_length, char *enumeration[], char *pattern[])`| Replace to support fault_msg in case of errors | -| function | `bbf_validate_string(char *value, int min_length, int max_length, char *enumeration[], char *pattern[])` | `int bbfdm_validate_string(struct dmctx *ctx, char *value, int min_length, int max_length, char *enumeration[], char *pattern[])`| Replace to support fault_msg in case of errors | -| function | `bbf_validate_boolean(char *value)` | `int bbfdm_validate_boolean(struct dmctx *ctx, char *value)` | Replace to support fault_msg in case of errors | -| function | `bbf_validate_unsignedInt(char *value, struct range_args r_args[], int r_args_size)` | `int bbfdm_validate_unsignedInt(struct dmctx *ctx, char *value, struct range_args r_args[], int r_args_size)` | Replace to support fault_msg in case of errors | -| function | `bbf_validate_int(char *value, struct range_args r_args[], int r_args_size)` | `int bbfdm_validate_int(struct dmctx *ctx, char *value, struct range_args r_args[], int r_args_size)` | Replace to support fault_msg in case of errors | -| function | `bbf_validate_unsignedLong(char *value, struct range_args r_args[], int r_args_size)` | `int bbfdm_validate_unsignedLong(struct dmctx *ctx, char *value, struct range_args r_args[], int r_args_size)` | Replace to support fault_msg in case of errors | -| function | `bbf_validate_long(char *value, struct range_args r_args[], int r_args_size)` | `int bbfdm_validate_long(struct dmctx *ctx, char *value, struct range_args r_args[], int r_args_size)` | Replace to support fault_msg in case of errors | -| function | `bbf_validate_dateTime(char *value)` | `int bbfdm_validate_dateTime(struct dmctx *ctx, char *value)` | Replace to support fault_msg in case of errors | -| function | `bbf_validate_hexBinary(char *value, struct range_args r_args[], int r_args_size)` | `int bbfdm_validate_hexBinary(struct dmctx *ctx, char *value, struct range_args r_args[], int r_args_size)` | Replace to support fault_msg in case of errors | -| function | `bbf_validate_string_list(char *value, int min_item, int max_item, int max_size, int min, int max, char *enumeration[], char *pattern[])` | `int bbfdm_validate_string_list(struct dmctx *ctx, char *value, int min_item, int max_item, int max_size, int min, int max, char *enumeration[], char *pattern[])` | Replace to support fault_msg in case of errors | -| function | `bbf_validate_unsignedInt_list(char *value, int min_item, int max_item, int max_size, struct range_args r_args[], int r_args_size)` | `int bbfdm_validate_unsignedInt_list(struct dmctx *ctx, char *value, int min_item, int max_item, int max_size, struct range_args r_args[], int r_args_size)` | Replace to support fault_msg in case of errors | -| function | `bbf_validate_int_list(char *value, int min_item, int max_item, int max_size, struct range_args r_args[], int r_args_size)` | `int bbfdm_validate_int_list(struct dmctx *ctx, char *value, int min_item, int max_item, int max_size, struct range_args r_args[], int r_args_size)` | Replace to support fault_msg in case of errors | -| function | `bbf_validate_unsignedLong_list(char *value, int min_item, int max_item, int max_size, struct range_args r_args[], int r_args_size)` | `int bbfdm_validate_unsignedLong_list(struct dmctx *ctx, char *value, int min_item, int max_item, int max_size, struct range_args r_args[], int r_args_size)` | Replace to support fault_msg in case of errors | -| function | `bbf_validate_long_list(char *value, int min_item, int max_item, int max_size, struct range_args r_args[], int r_args_size)` | `int bbfdm_validate_long_list(struct dmctx *ctx, char *value, int min_item, int max_item, int max_size, struct range_args r_args[], int r_args_size)`| Replace to support fault_msg in case of errors | -| function | `bbf_validate_hexBinary_list(char *value, int min_item, int max_item, int max_size, struct range_args r_args[], int r_args_size)` | `int bbfdm_validate_hexBinary_list(struct dmctx *ctx, char *value, int min_item, int max_item, int max_size, struct range_args r_args[], int r_args_size)` | Replace to support fault_msg in case of errors | -| function | `dm_validate_boolean(char *value)` | `int bbfdm_validate_boolean(struct dmctx *ctx, char *value)` | Replace to support fault_msg in case of errors | -| function | `dm_validate_unsignedInt(char *value, struct range_args r_args[], int r_args_size)` | `int bbfdm_validate_unsignedInt(struct dmctx *ctx, char *value, struct range_args r_args[], int r_args_size)` | Replace to support fault_msg in case of errors | -| function | `dm_validate_int(char *value, struct range_args r_args[], int r_args_size)` | `int bbfdm_validate_int(struct dmctx *ctx, char *value, struct range_args r_args[], int r_args_size)` | Replace to support fault_msg in case of errors | -| function | `dm_validate_unsignedLong(char *value, struct range_args r_args[], int r_args_size)` | `int bbfdm_validate_unsignedLong(struct dmctx *ctx, char *value, struct range_args r_args[], int r_args_size)` | Replace to support fault_msg in case of errors | -| function | `dm_validate_long(char *value, struct range_args r_args[], int r_args_size)` | `int bbfdm_validate_long(struct dmctx *ctx, char *value, struct range_args r_args[], int r_args_size)` | Replace to support fault_msg in case of errors | -| function | `dm_validate_dateTime(char *value)` | `int bbfdm_validate_dateTime(struct dmctx *ctx, char *value)` | Replace to support fault_msg in case of errors | -| function | `dm_validate_hexBinary(char *value, struct range_args r_args[], int r_args_size)` | `int bbfdm_validate_hexBinary(struct dmctx *ctx, char *value, struct range_args r_args[], int r_args_size)` | Replace to support fault_msg in case of errors | -| function | `dm_validate_string_list(char *value, int min_item, int max_item, int max_size, int min, int max, char *enumeration[], char *pattern[])` | `int bbfdm_validate_string_list(struct dmctx *ctx, char *value, int min_item, int max_item, int max_size, int min, int max, char *enumeration[], char *pattern[])` | Replace to support fault_msg in case of errors | -| function | `dm_validate_unsignedInt_list(char *value, int min_item, int max_item, int max_size, struct range_args r_args[], int r_args_size)` | `int bbfdm_validate_unsignedInt_list(struct dmctx *ctx, char *value, int min_item, int max_item, int max_size, struct range_args r_args[], int r_args_size)` | Replace to support fault_msg in case of errors | -| function | `dm_validate_int_list(char *value, int min_item, int max_item, int max_size, struct range_args r_args[], int r_args_size)` | `int bbfdm_validate_int_list(struct dmctx *ctx, char *value, int min_item, int max_item, int max_size, struct range_args r_args[], int r_args_size)` | Replace to support fault_msg in case of errors | -| function | `dm_validate_unsignedLong_list(char *value, int min_item, int max_item, int max_size, struct range_args r_args[], int r_args_size)` | `int bbfdm_validate_unsignedLong_list(struct dmctx *ctx, char *value, int min_item, int max_item, int max_size, struct range_args r_args[], int r_args_size)` | Replace to support fault_msg in case of errors | -| function | `dm_validate_long_list(char *value, int min_item, int max_item, int max_size, struct range_args r_args[], int r_args_size)` | `int bbfdm_validate_long_list(struct dmctx *ctx, char *value, int min_item, int max_item, int max_size, struct range_args r_args[], int r_args_size)`| Replace to support fault_msg in case of errors | -| function | `dm_validate_hexBinary_list(char *value, int min_item, int max_item, int max_size, struct range_args r_args[], int r_args_size)` | `int bbfdm_validate_hexBinary_list(struct dmctx *ctx, char *value, int min_item, int max_item, int max_size, struct range_args r_args[], int r_args_size)` | Replace to support fault_msg in case of errors | -| function | `int dm_entry_validate_allowed_objects(struct dmctx *ctx, char *value, char *objects[])` | `int dm_validate_allowed_objects(struct dmctx *ctx, struct dm_reference *reference, char *objects[])` | Replaced with a generic API that is accessible for both internal (bbfdm core) and external (microservices) data models | -| function | `int dm_entry_validate_external_linker_allowed_objects(struct dmctx *ctx, char *value, char *objects[])` | `int dm_validate_allowed_objects(struct dmctx *ctx, struct dm_reference *reference, char *objects[])` | Replaced with a generic API that is accessible for both internal (bbfdm core) and external (microservices) data models | -| function | `int adm_entry_get_linker_param(struct dmctx *ctx, char *param, char *linker, char **value)` | | Removed, no more required | -| function | `int adm_entry_get_linker_value(struct dmctx *ctx, char *param, char **value)` | | Removed, no more required | -| enum | `CMD_SUCCESS` | | Removed, no more required | -| enum | `CMD_INVALID_ARGUMENTS` | | Removed, no more required | -| enum | `CMD_FAIL` | | Removed, no more required | -| enum | `CMD_NOT_FOUND` | | Removed, no more required | -| enum | `__STATUS_MAX` | | Removed, no more required | - diff --git a/docs/guide/libbbfdm-api_obj_param_extension.md b/docs/guide/libbbfdm-api_obj_param_extension.md deleted file mode 100644 index d21aac55..00000000 --- a/docs/guide/libbbfdm-api_obj_param_extension.md +++ /dev/null @@ -1,167 +0,0 @@ -# How to add support for a new Object/Parameter - -As mentioned in README, all Data Models are stored in the **'dmtree'** folder. In order to implement a new object/parameter, you need to expand its get/set/add/delete functions and then save them in the right folder. - -`bbfdm` library offers a tool to generate templates of the source code from json files placed under **'dmtree/json'**. So, any developer can fill the data model json file [data_model](../../libbbfdm/dmtree/json/datamodel.json) with mapping field according to UCI, UBUS or CLI commands then generate the source code in C. - -```bash -$ ./convert_dm_json_to_c.py -Usage: ./tools/convert_dm_json_to_c.py [Object path] -Examples: - - ./tools/convert_dm_json_to_c.py - ==> Generate the C code of full data model in datamodel/ folder - - ./tools/convert_dm_json_to_c.py Device.DeviceInfo. - ==> Generate the C code of Device.DeviceInfo object in datamodel/ folder -``` - -Below some examples of **UCI**, **UBUS** or **CLI** mappings: - -#### UCI command - -- **@Name:** the section name of parent object - -- **@i:** is the number of instance object - -```bash - "mapping": [ - { - "type": "uci", - "uci": { - "file": "wireless", - "section": { - "type": "wifi-device", - "name": "@Name", - "index": "@i-1" - }, - "option": { - "name": "disabled" - } - } - } - ] -``` - -#### UBUS command - -- **@Name:** the section name of parent object - -```bash - "mapping": [ - { - "type": "ubus", - "ubus": { - "object": "network.device", - "method": "status", - "args": { - "name": "@Name" - }, - "key": "statistics.rx_bytes" - } - } - ] -``` - -#### CLI command: - -- **@Name:** the section name of parent object - -- **-i:** is the number of arguments command - -```bash - "mapping": [ - { - "type" : "cli", - "cli" : { - "command" : "wlctl", - "args" : [ - "-i", - "@Name", - "bands" - ] - } - } - ] -``` - -After building the templates of C source code, a **datamodel** folder will be generated under **'tools'** folder that contains all files related to each object under root "**Device.**" - -> Note: You can generate the source code without filling out the mapping field in the JSON file - -### Object definition - -Each object in the **DMOBJ** table contains the following arguments: - -| Argument | Description | -| ------------------- | ---------------------------------------------------------------------------------------------- | -| `OBJ` | A string of the object name. Example “Bridging”, “IP”, “DeviceInfo”, “WiFi” | -| `permission` | The permission of the object. Could be **&DMREAD** or **&DMWRITE**. If it's `&DMWRITE` then we can add/delete instances of this object | -| `addobj` | The function to add new instance under this object. This function will be triggered when the ACS/Controller call AddObject of this object | -| `delobj` | The function to delete instance under this object. This function will be triggered when the ACS/Controller call DeleteObject of an instance of this object | -| `checkdep` | A string of the object dependency, it can be a file("file:/etc/config/network") or an ubus object,method("ubus:network.interface->status"). If it's `NULL` then the object has always appeared in the tree | -| `browseinstobj` | This function allow to browse all instances under this object | -| `nextdynamicobj` | Pointer to the next of **DMOBJ** which contains a list of the child objects using json files, shared libraries and vendor extension | -| `dynamicleaf` | Pointer to the next of **DMLEAF** which contains a list of the child parameters using json files, shared libraries and vendor extension | -| `nextobj` | Pointer to a **DMOBJ** array which contains a list of the child objects | -| `leaf` | Pointer to a **DMLEAF** array which contains a list of the child parameters | -| `linker` | This argument is deprecated and should be `NULL` | -| `bbfdm_type` | The bbfdm type of the object. Could be **BBFDM_CWMP**, **BBFDM_USP**, **BBFDM_BOTH** or **BBFDM_NONE**.If it's **BBFDM_BOTH** then we can see this object in all protocols (CWMP, USP,...) | -| `uniqueKeys` | This argument is deprecated and should be `NULL` | - -### Leaf definition - -Each leaf in the **DMLEAF** table can be a **Parameter**, **Command** or **Event**. - - -#### 1.Parameter definition - -| Argument | Description | -| ------------------- | -------------------------------------------------------------------------------------------------- | -| `PARAM` | A string of the parameter name. Example “Enable”, “Status”, “Name” | -| `permission` | The permission of the parameter. Could be **&DMREAD** or **&DMWRITE**.If it's `&DMWRITE` then we can set a value for this parameter | -| `type` | Type of the parameter: **DM_STRING**, **DM_BOOL**, **DM_UNINT**,... | -| `getvalue` | The function which return the value of this parameter | -| `setvalue` | The function which set the value of this parameter | -| `bbfdm_type` | The bbfdm type of the parameter. Could be **BBFDM_CWMP**, **BBFDM_USP**, **BBFDM_BOTH** or **BBFDM_NONE**.If it's **BBFDM_BOTH** then we can see this parameter in all protocols (CWMP, USP,...) | -| `dm_falgs` | An enumeration value used to specify the displayed parameter value. Could be **DM_FLAG_REFERENCE**, **DM_FLAG_UNIQUE**, **DM_FLAG_LINKER** or **DM_FLAG_SECURE**. | - -#### 2.Command definition - -| Argument | Description | -| ------------------- | -------------------------------------------------------------------------------------------------- | -| `PARAM` | A string of the command name. Example “IPPing()”, “DownloadDiagnostics()”, “Renew()” | -| `permission` | The permission of the command. Could be **&DMASYNC** or **&DMSYNC**. | -| `type` | Type of the command, It should be **DMT_COMMAND** | -| `getvalue` | The function which return the input, output arguments of the command | -| `setvalue` | The function which call the operation of the command | -| `bbfdm_type` | The bbfdm type of the command. It should be **BBFDM_USP** as long as operate commands are only defined in USP protocol. | - - -#### 3.Event definition - -| Argument | Description | -| ------------------- | -------------------------------------------------------------------------------------------------- | -| `PARAM` | A string of the event name. Example “Boot!”, “Push!”, “Periodic!” | -| `permission` | The permission of the event. It should be **DMREAD** | -| `type` | Type of the event, It should be **DMT_EVENT** | -| `getvalue` | The function which return the parameter arguments of the event | -| `setvalue` | The function which call the operation of the event | -| `bbfdm_type` | The bbfdm type of the event. It should be **BBFDM_USP** as long as events are only defined in USP protocol. | - - -### Browse definition - -The browse function allow to go over all instances of the current object and link them to the data model tree. - -In this function, there are two functions that need to be defined: - -- function to retrieve the instances: it can be: - - * `handle_instance` function: allow to retrieve/attribute the instances number/alias from uci config sections depending of the request and the instance mode. - - * `handle_instance_without_section` function: allow to attribute the instances number/alias with constant values. - -- function to link the instances: To link each instance to the data model tree, it's necessary to call `DM_LINK_INST_OBJ()` API for every instance. Additionally, it's **mandatory** to use the generic structure `(struct dm_data *)` as passed `data` at each instance level in order to maintain the capability to extend the data model using `JSON` plugin. This structure will be utilized later in functions related to sub-objects and parameters (Get/Set/Add/Delete/Operate/Event). - -> Note1: the browse function is only developed for multi-instances objects. - -> Note2: you can use [bbf_test plugin](../../test/bbf_test/bbf_test.c) as a reference in order to develop any new object/leaf/browse. diff --git a/docs/guide/libbbfdm-api_vendor.md b/docs/guide/libbbfdm-api_vendor.md deleted file mode 100644 index 1255cfab..00000000 --- a/docs/guide/libbbfdm-api_vendor.md +++ /dev/null @@ -1,82 +0,0 @@ -# BBFDM Vendor - -The `bbfdm` library offers functionality for vendors to define their vendor extensions. This allows them to **extend** the core Data Model by introducing new objects/parameters/operates/events, **overwrite** and **exclude** existing ones. - -## How to Add a New Vendor - -### 1. Create a Vendor Folder - -To add a new vendor, simply create a new folder under **'dmtree/vendor/'** which contains all files related to the vendor. Ensure that the folder name matches the vendor name specified in **BBF_VENDOR_LIST** macro. - -### 2. Populate the `tDynamicObj` Table - -For extending, overwriting, and excluding objects/parameters/operates/events from the core tree, it's mandatory to have a `tDynamicObj` table. This table should be defined using **DM_MAP_OBJ** structure, which has three arguments: - -| Argument | Description | -| ---------------- | ------------------------------------------------------------------------------------------------------------- | -| `parentobj` | A string representing the parent object name from which to extend/exclude/overwrite the required items. Example: "Device.IP.Diagnostics.", "Device.WiFi.Radio." | -| `nextobject` | Pointer to a **DMOBJ** array containing a list of child objects to extend/exclude/overwrite | -| `parameter` | Pointer to a **DMLEAF** array containing a list of child parameters to extend/exclude/overwrite | - - -- The `parentobj` must be a string path of an **object** available in the core tree. If it doesn't exist, it will be skipped during parsing of the `tDynamicObj` table. - -- To extend the Data Model tree, fill the `nextobject` and `parameter` arguments with the required objects/parameters/operates/events not supported by the core tree. - -- To overwrite existing objects/parameters/operates/events in the core tree, fill the `nextobject` and `parameter` arguments with the same items defined in the core tree, along with new **add/del/get/set/browse** APIs needed by the vendor. - -- To exclude existing objects/parameters/operates/events in the core tree, fill the `nextobject` and `parameter` arguments with the same items defined in the core tree, and setting **bbfdm_type** to **BBFDM_NONE**. - -### 3. Enable vendor - -To enable the new vendor: - -- Add the vendor to the list in **BBF_VENDOR_LIST** macro. - -- Define the vendor prefix using **BBF_VENDOR_PREFIX** macro. - -Example Configuration Options: - -```bash -BBF_VENDOR_LIST="iopsys,xxxx" -BBF_VENDOR_PREFIX="X_IOPSYS_EU_" -``` - -## Example how to Extend, Overwrite and Exclude the Data Model tree - -In the [test/vendor_test/](../../test/vendor_test) directory, you'll find an example implementation for **test** vendor. This implementation demonstrates how to extend, overwrite, and exclude objects/parameters/operates/events from the core tree. - -### 1. Extend Data Model - -- using DotSo Plugin: - - Add support for [Device.Firewall.Chain.{i}.Rule.{i}.X_TEST_COM_TimeSpan.](../../test/vendor_test/firewall.c#L172) object - - Add support for [Device.Firewall.Chain.{i}.Rule.{i}.X_TEST_COM_ICMPType](../../test/vendor_test/firewall.c#L178) parameter - -- using JSON Plugin: - - Add support for [Device.PD2.{i}.](../../test/vendor_test/test_extend.json#L60) object - - Add support for [Device.WiFi.X_IOPSYS_EU_TEST1](../../test/vendor_test/test_extend.json#L11) parameter - -### 2. Overwrite Data Model - -- using DotSo Plugin: - - Overwrite [Device.X_IOPSYS_EU_Dropbear.{i}.](../../test/vendor_test/device.c#L18) object in the core tree - - Overwrite [Device.DeviceInfo.Manufacturer](../../test/vendor_test/deviceinfo.c#L29) parameter in the core tree - -- using JSON Plugin: - - Overwrite [Device.DeviceInfo.Processor.](../../test/vendor_test/test_overwrite.json#L11) object in the core tree - - Overwrite [Device.DeviceInfo.ProcessorNumberOfEntries](../../test/vendor_test/test_overwrite.json#L30) parameter in the core tree - -### 3. Exclude Data Model - -- using DotSo Plugin: - - Exclude [Device.USB.](../../test/vendor_test/device.c#L17) object from the core tree - - Exclude [Device.Ethernet.RMONStats.{i}.Packets1024to1518Bytes](../../test/vendor_test/extension.c#L37) parameter from the core tree - -- using JSON Plugin: - - Exclude [Device.X_IOPSYS_EU_IGMP.](../../test/vendor_test/test_exclude.json#L28) object from the core tree - - Exclude [Device.InterfaceStackNumberOfEntries](../../test/vendor_test/test_exclude.json#L52) parameter from the core tree - - -> Note1: The `libbbfdm` vendor list can support multiple vendors, separated by commas. - -> Note2: If multi vendors are supported and there is an objects/parameters/operates/events implemented differently by different vendors, the implementation of the **last vendor name** in **BBF_VENDOR_LIST** will be considered. diff --git a/gitlab-ci/bbfdmd-functional-test.sh b/gitlab-ci/bbfdmd-functional-test.sh index a35357e4..3d379e64 100755 --- a/gitlab-ci/bbfdmd-functional-test.sh +++ b/gitlab-ci/bbfdmd-functional-test.sh @@ -43,7 +43,7 @@ echo "1..${num}" >> ./funl-result.log generate_report python_test ./funl-result.log # run functional on bbf object validation -cp -r ./schemas/ubus/bbfdm.json /usr/share/rpcd/schemas/bbf.json +cp -r ./docs/api/ubus/bbfdm.json /usr/share/rpcd/schemas/bbf.json ubus-api-validator -t 10 -f ./test/funl/validation/bbf.validation.json > ./funl-result.log fault=$? generate_report bbf_positive ./funl-result.log diff --git a/libbbfdm/CMakeLists.txt b/libbbfdm/CMakeLists.txt index 39cc1a00..df737abb 100644 --- a/libbbfdm/CMakeLists.txt +++ b/libbbfdm/CMakeLists.txt @@ -29,19 +29,12 @@ INSTALL(TARGETS bbfdm INSTALL(DIRECTORY DESTINATION etc/bbfdm) INSTALL(DIRECTORY DESTINATION etc/bbfdm/dmmap) +INSTALL(DIRECTORY DESTINATION usr/share/bbfdm/scripts) INSTALL(DIRECTORY DESTINATION usr/share/bbfdm/plugins) INSTALL(DIRECTORY DESTINATION usr/share/bbfdm/micro_services) INSTALL(DIRECTORY DESTINATION usr/share/bbfdm) INSTALL(DIRECTORY DESTINATION usr/libexec/rpcd) -FILE(GLOB scripts scripts/*) - -FOREACH(script ${scripts}) - INSTALL(FILES ${script} - PERMISSIONS OWNER_EXECUTE - DESTINATION usr/share/bbfdm/scripts - ) -ENDFOREACH() string(REPLACE "," ";" VENDOR_LIST ${BBF_VENDOR_LIST}) diff --git a/libbbfdm/dmtree/vendor/iopsys/vendor.json b/libbbfdm/dmtree/vendor/iopsys/vendor.json index 6b438620..87dbd752 100644 --- a/libbbfdm/dmtree/vendor/iopsys/vendor.json +++ b/libbbfdm/dmtree/vendor/iopsys/vendor.json @@ -8,458 +8,6 @@ "description": "The top-level object for a Device.", "access": false, "array": false, - "Device.Services.": { - "type": "object", - "protocols": [ - "cwmp", - "usp" - ], - "description": "This object contains general services information.", - "access": false, - "array": false, - "Device.Services.VoiceService.{i}.": { - "type": "object", - "protocols": [ - "cwmp", - "usp" - ], - "description": "The top-level object for VoIP CPE. At most one entry in this table can exist with a given value for Alias.", - "access": true, - "array": true, - "Device.Services.VoiceService.{i}.CallLog.{i}.": { - "type": "object", - "protocols": [ - "cwmp", - "usp" - ], - "description": "Contains a list of calls log.An entry is created each time a call is terminated.", - "access": false, - "array": true, - "{BBF_VENDOR_PREFIX}SIPIPAddress": { - "type": "string", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "URI that addresses a specific extension on a voice over IP system.", - "datatype": "string" - }, - "{BBF_VENDOR_PREFIX}SIPResponseCode": { - "type": "unsignedInt", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "SIP response code is three-digit integer code which gives status of the request.", - "datatype": "unsignedInt" - }, - "Device.Services.VoiceService.{i}.CallLog.{i}.Session.{i}.": { - "type": "object", - "protocols": [ - "cwmp", - "usp" - ], - "description": "Session information within one call. At most one entry in this table can exist with a given value for <>.", - "access": false, - "array": true, - "Device.Services.VoiceService.{i}.CallLog.{i}.Session.{i}.Destination.": { - "type": "object", - "protocols": [ - "cwmp", - "usp" - ], - "description": "The destination part of session information within one call.", - "access": false, - "array": false, - "Device.Services.VoiceService.{i}.CallLog.{i}.Session.{i}.Destination.RTP.": { - "type": "object", - "protocols": [ - "cwmp", - "usp" - ], - "access": false, - "array": false, - "description": "The RTP part of the destination session information.", - "{BBF_VENDOR_PREFIX}BurstDensity": { - "type": "unsignedInt", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "The fraction of RTP data packets within burst periods since the beginning of reception that were either lost or discarded.", - "datatype": "unsignedInt" - }, - "{BBF_VENDOR_PREFIX}BurstDuration": { - "type": "unsignedInt", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "The mean duration, expressed in milliseconds, of the burst periods that have occurred since the beginning of reception.", - "datatype": "unsignedInt" - }, - "{BBF_VENDOR_PREFIX}GapDensity": { - "type": "unsignedInt", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "The fraction of RTP data packets within inter-burst gaps since the beginning of reception that were either lost or discarded.", - "datatype": "unsignedInt" - }, - "{BBF_VENDOR_PREFIX}GapDuration": { - "type": "unsignedInt", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "The mean duration, expressed in milliseconds, of the gap periods that have occurred since the beginning of reception.", - "datatype": "unsignedInt" - }, - "{BBF_VENDOR_PREFIX}JBAvgDelay": { - "type": "unsignedInt", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Average jitter buffer delay in milliseconds which corresponds to the earliest arriving packet that would not be discarded.", - "datatype": "unsignedInt" - }, - "{BBF_VENDOR_PREFIX}JBMaxDelay": { - "type": "unsignedInt", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Maximum jitter buffer delay in milliseconds which corresponds to the earliest arriving packet that would not be discarded.", - "datatype": "unsignedInt" - }, - "{BBF_VENDOR_PREFIX}JBNomDelay": { - "type": "unsignedInt", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Nominal jitter buffer delay in milliseconds, which corresponds to the nominal jitter buffer delay for packets that arrive exactly on time.", - "datatype": "unsignedInt" - }, - "{BBF_VENDOR_PREFIX}PeakJitter": { - "type": "unsignedInt", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Peak jitter / holding time (in milliseconds).", - "datatype": "unsignedInt" - } - } - }, - "Device.Services.VoiceService.{i}.CallLog.{i}.Session.{i}.Source.": { - "type": "object", - "protocols": [ - "cwmp", - "usp" - ], - "description": "The source of the session information within one call.", - "access": false, - "array": false, - "Device.Services.VoiceService.{i}.CallLog.{i}.Session.{i}.Source.RTP.": { - "type": "object", - "protocols": [ - "cwmp", - "usp" - ], - "description": "The RTP part of the source session information.", - "access": false, - "array": false, - "{BBF_VENDOR_PREFIX}BurstDensity": { - "type": "unsignedInt", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "The fraction of RTP data packets within burst periods since the beginning of reception that were either lost or discarded.", - "datatype": "unsignedInt" - }, - "{BBF_VENDOR_PREFIX}BurstDuration": { - "type": "unsignedInt", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "The mean duration, expressed in milliseconds, of the burst periods that have occurred since the beginning of reception.", - "datatype": "unsignedInt" - }, - "{BBF_VENDOR_PREFIX}GapDensity": { - "type": "unsignedInt", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "The fraction of RTP data packets within inter-burst gaps since the beginning of reception that were either lost or discarded.", - "datatype": "unsignedInt" - }, - "{BBF_VENDOR_PREFIX}GapDuration": { - "type": "unsignedInt", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "The mean duration, expressed in milliseconds, of the gap periods that have occurred since the beginning of reception.", - "datatype": "unsignedInt" - }, - "{BBF_VENDOR_PREFIX}JBAvgDelay": { - "type": "unsignedInt", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Average jitter buffer delay in milliseconds which corresponds to the earliest arriving packet that would not be discarded.", - "datatype": "unsignedInt" - }, - "{BBF_VENDOR_PREFIX}JBMaxDelay": { - "type": "unsignedInt", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Maximum jitter buffer delay in milliseconds which corresponds to the earliest arriving packet that would not be discarded.", - "datatype": "unsignedInt" - }, - "{BBF_VENDOR_PREFIX}JBNomDelay": { - "type": "unsignedInt", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Nominal jitter buffer delay in milliseconds, which corresponds to the nominal jitter buffer delay for packets that arrive exactly on time.", - "datatype": "unsignedInt" - }, - "{BBF_VENDOR_PREFIX}PeakJitter": { - "type": "unsignedInt", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Peak jitter / holding time (in milliseconds).", - "datatype": "unsignedInt" - } - } - } - } - }, - "Device.Services.VoiceService.{i}.CallControl.": { - "type": "object", - "protocols": [ - "cwmp", - "usp" - ], - "description": "Call control and call routing parameters. This object is a control plane application for the VoiceService that provides numbers or names based routing, local PBX functionalities and advanced telephony features. It is mutually exclusive with the <> table which is used in case of switching capabilities.", - "access": false, - "array": false, - "Device.Services.VoiceService.{i}.CallControl.Extension.{i}.": { - "type": "object", - "protocols": [ - "cwmp", - "usp" - ], - "description": "Extension table containing the local numbers and names.", - "access": true, - "array": true, - "{BBF_VENDOR_PREFIX}ComfortNoise": { - "type": "boolean", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Comfort Noise is enabled/disabled.", - "datatype": "boolean" - }, - "{BBF_VENDOR_PREFIX}TXGain": { - "type": "string", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Control the audio transmitted to the extension.The numbers represent db (decibels).", - "datatype": "string", - "range": [ - { - "max": 32 - } - ] - }, - "{BBF_VENDOR_PREFIX}RXGain": { - "type": "string", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Control the audio received at the extension .The numbers represent db (decibels).", - "datatype": "string", - "range": [ - { - "max": 32 - } - ] - }, - "{BBF_VENDOR_PREFIX}EchoCancel": { - "type": "boolean", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Enable or disable echo cancellation for this extension.", - "datatype": "boolean" - }, - "{BBF_VENDOR_PREFIX}Type": { - "type": "string", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Specfies the type of the extension fxs/dect.", - "datatype": "string", - "range": [ - { - "max": 32 - } - ] - } - } - }, - "Device.Services.VoiceService.{i}.DECT.": { - "type": "object", - "protocols": [ - "cwmp", - "usp" - ], - "description": "DECT portable table.", - "access": false, - "array": false, - "Device.Services.VoiceService.{i}.DECT.Portable.{i}.": { - "type": "object", - "protocols": [ - "cwmp", - "usp" - ], - "description": "DECT portable table.", - "access": true, - "array": true, - "{BBF_VENDOR_PREFIX}Name": { - "type": "string", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Indicates the name of this DECT portable.", - "datatype": "string" - } - } - } - } - }, - "Device.Bridging.": { - "type": "object", - "protocols": [ - "cwmp", - "usp" - ], - "description": "Layer 2 bridging configuration. Specifies bridges between different layer 2 interfaces. Bridges can be defined to include layer 2 filter criteria to selectively bridge traffic between interfaces. This object can be used to configure both 802.1D <> and 802.1Q <> bridges. Not all 802.1D and 802.1Q features are modeled, and some additional features not present in either 802.1D or 802.1Q are modeled. 802.1Q <> bridges incorporate 802.1Q <> customer and 802.1ad <> provider bridges.", - "access": false, - "array": false, - "Device.Bridging.Bridge.{i}.": { - "type": "object", - "protocols": [ - "cwmp", - "usp" - ], - "description": "Bridge table.", - "access": true, - "array": true, - "Device.Bridging.Bridge.{i}.Port.{i}.": { - "type": "object", - "protocols": [ - "cwmp", - "usp" - ], - "description": "Bridge Port table, which MUST contain an entry for each bridge port (a stackable interface object as described in <>). There are two types of bridge ports: management (upward facing) and non-management (downward facing). This is determined by configuring the Boolean <> parameter. The CPE will automatically configure each management bridge port to appear in the interface stack above all non-management bridge ports that share the same <> instance.", - "access": true, - "array": true, - "{BBF_VENDOR_PREFIX}EgressPriorityRegeneration": { - "type": "string", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Rewriting priority on egress, to map the pbit value of incoming packet to another value and emit it with that", - "list": { - "datatype": "unsignedInt", - "item": { - "min": 8, - "max": 8 - }, - "range": [ - { - "min": 0, - "max": 7 - } - ] - } - } - } - } - }, "Device.DeviceInfo.": { "type": "object", "protocols": [ @@ -489,1295 +37,6 @@ "([0-9A-Fa-f][0-9A-Fa-f]:){5}([0-9A-Fa-f][0-9A-Fa-f])" ] } - }, - "Device.Ethernet.": { - "type": "object", - "protocols": [ - "cwmp", - "usp" - ], - "description": "Ethernet object. This object models several Ethernet interface objects, each representing a different stack layer, including: <>, <>, and <>. <> is media-specific and models a port, the PHY layer, and the Channel Access Method (CAM) part of the MAC layer. <> is media-independent and models the Logical Link Control (LLC) layer. An outer <>, when present, is expected to be stacked on top of <> objects to receive and send frames with a configured VLANID.", - "access": false, - "array": false, - "Device.Ethernet.{BBF_VENDOR_PREFIX}MACVLAN.{i}.": { - "type": "object", - "protocols": [ - "cwmp", - "usp" - ], - "description": "A MACVLAN entry is typically stacked on top of a <> object or <> to receive and send frames with the configured <>.", - "access": true, - "array": true, - "Enable": { - "type": "boolean", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Enables or disables the MACVLAN entry", - "default": "false", - "datatype": "boolean" - }, - "Status": { - "type": "string", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "The current operational state of the MACVLAN entry. Enumeration of: Up, Down, Unknown, Dormant, NotPresent, LowerLayerDown, Error. When <> is <> then <> SHOULD normally be <> (or <> or <> if there is a fault condition on the interface). When <> is changed to <> then <> SHOULD change to <> if and only if the interface is able to transmit and receive network traffic; it SHOULD change to <> if and only if the interface is operable but is waiting for external actions before it can transmit and receive network traffic (and subsequently change to <> if still operable when the expected actions have completed); it SHOULD change to <> if and only if the interface is prevented from entering the <> state because one or more of the interfaces beneath it is down; it SHOULD remain in the <> state if there is an error or other fault condition detected on the interface; it SHOULD remain in the <> state if the interface has missing (typically hardware) components; it SHOULD change to <> if the state of the interface can not be determined for some reason. This parameter is based on ifOperStatus from <>.", - "default": "Down", - "datatype": "string", - "enumerations": [ - "Up", - "Down", - "Unknown", - "Dormant", - "NotPresent", - "LowerLayerDown", - "Error" - ] - }, - "Alias": { - "type": "string", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "A non-volatile handle used to reference this instance. Alias provides a mechanism for an ACS to label this instance for future reference. If the CPE supports the Alias-based Addressing feature as defined in <> and described in <>, the following mandatory constraints MUST be enforced: * Its value MUST NOT be empty. * Its value MUST start with a letter. * If its value is not assigned by the ACS, it MUST start with a cpe- prefix. * The CPE MUST NOT change the parameter value. | A non-volatile handle used to reference this instance. Alias provides a mechanism for an ACS to label this instance for future reference. If the CPE supports the Alias-based Addressing feature as defined in <> and described in <>, the following mandatory constraints MUST be enforced: * Its value MUST NOT be empty. * Its value MUST start with a letter. * If its value is not assigned by the ACS, it MUST start with a cpe- prefix. * The CPE MUST NOT change the parameter value.", - "datatype": "Alias", - "range": [ - { - "max": 64 - } - ] - }, - "Name": { - "type": "string", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "The textual name of the MACVLAN entry as assigned by the CPE.", - "datatype": "string", - "range": [ - { - "max": 64 - } - ] - }, - "LowerLayers": { - "type": "string", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "<> <> See <>.", - "list": { - "datatype": "string", - "maxsize": 1024 - } - }, - "MACAddress": { - "type": "string", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "The MAC address used for packets sent via this interface. Provides the source MAC address for outgoing traffic and the destination MAC address for incoming traffic.", - "datatype": "MACAddress", - "range": [ - { - "max": 17 - } - ], - "pattern": [ - "", - "([0-9A-Fa-f][0-9A-Fa-f]:){5}([0-9A-Fa-f][0-9A-Fa-f])" - ] - }, - "Device.Ethernet.{BBF_VENDOR_PREFIX}MACVLAN.{i}.Stats.": { - "type": "object", - "protocols": [ - "cwmp", - "usp" - ], - "description": "Throughput statistics for this MACVLAN entry. The CPE MUST reset the links Stats parameters (unless otherwise stated in individual object or parameter descriptions) either when the link becomes operationally down due to a previous administrative down (i.e. the links <> parameter transitions to a down state after the link is disabled) or when the link becomes administratively up (i.e. the links <> parameter transitions from <> to <>). Administrative and operational link status is discussed in <>.", - "access": false, - "array": false, - "BytesSent": { - "type": "unsignedLong", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "The total number of bytes transmitted out of the MACVLAN entry, including framing characters.", - "datatype": "unsignedLong" - }, - "BytesReceived": { - "type": "unsignedLong", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "The total number of bytes received on the MACVLAN entry, including framing characters.", - "datatype": "unsignedLong" - }, - "PacketsSent": { - "type": "unsignedLong", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "The total number of Ethernet frames transmitted out of the MACVLAN entry.", - "datatype": "unsignedLong" - }, - "PacketsReceived": { - "type": "unsignedLong", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "The total number of Ethernet frames received on the MACVLAN entry.", - "datatype": "unsignedLong" - }, - "ErrorsSent": { - "type": "unsignedInt", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "The total number of outbound Ethernet frames that could not be transmitted because of errors.", - "datatype": "unsignedInt" - }, - "ErrorsReceived": { - "type": "unsignedInt", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "The total number of inbound Ethernet frames that contained errors preventing them from being delivered to a higher-layer protocol.", - "datatype": "unsignedInt" - }, - "DiscardPacketsSent": { - "type": "unsignedInt", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "The total number of outbound Ethernet frames which were chosen to be discarded even though no errors had been detected to prevent their being transmitted. One possible reason for discarding such a packet could be to free up buffer space.", - "datatype": "unsignedInt" - }, - "DiscardPacketsReceived": { - "type": "unsignedInt", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "The total number of inbound Ethernet frames which were chosen to be discarded even though no errors had been detected to prevent their being delivered. One possible reason for discarding such a packet could be to free up buffer space.", - "datatype": "unsignedInt" - }, - "MulticastPacketsReceived": { - "type": "unsignedLong", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "The total number of received Ethernet frames, delivered by this layer to a higher layer, which were addressed to a multicast address at this layer.", - "datatype": "unsignedLong" - } - } - } - }, - "Device.Time.": { - "type": "object", - "protocols": [ - "cwmp", - "usp" - ], - "description": "This object contains parameters relating an NTP or SNTP time client in the CPE.", - "access": false, - "array": false, - "{BBF_VENDOR_PREFIX}LocalTimeZoneName": { - "type": "string", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "The local zone name definition.", - "datatype": "string" - }, - "{BBF_VENDOR_PREFIX}SourceInterface": { - "type": "string", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Identifier of the IP interface in the device. This parameter can be an entry in the table <.>>.", - "datatype": "string" - } - }, - "Device.{BBF_VENDOR_PREFIX}IGMP.": { - "type": "object", - "protocols": [ - "cwmp", - "usp" - ], - "description": "Object contains parameters related to IGMP settings for IPTV service", - "access": false, - "array": false, - "SnoopingNumberOfEntries": { - "type": "unsignedInt", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "<>", - "datatype": "unsignedInt" - }, - "ProxyNumberOfEntries": { - "type": "unsignedInt", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "<>", - "datatype": "unsignedInt" - }, - "Device.{BBF_VENDOR_PREFIX}IGMP.Snooping.{i}.": { - "type": "object", - "protocols": [ - "cwmp", - "usp" - ], - "description": "Object contains parameters for configuring IGMP snooping", - "access": true, - "array": true, - "Enable": { - "type": "boolean", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Indicates whether or not the IGMP snooping is enabled.", - "datatype": "boolean" - }, - "Version": { - "type": "string", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Indicates the version of IGMP.", - "datatype": "string", - "enumerations": [ - "V2", - "V3" - ] - }, - "Robustness": { - "type": "unsignedInt", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Number of times for retransmitting IGMP queries in case of packet loss. A higher robustness variable makes the IGMP querier more robust.", - "datatype": "unsignedInt", - "range": [ - { - "max": 65535 - } - ] - }, - "Aggregation": { - "type": "boolean", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "This enables the device to forward only the first IGMP report for a multicast group to its directly connected Layer 3 device", - "datatype": "boolean" - }, - "Interface": { - "type": "string", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Path of object on which to snoop, usually a bridge", - "datatype": "string" - }, - "Mode": { - "type": "string", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Multicast snooping mode, when defined as standard, unknown stream flooded on all ports of the bridge, when defined as blocking unknown streams dropped it, when defined as disabled it disabled the multicast traffic.", - "datatype": "string", - "enumerations": [ - "Standard", - "Blocking", - "Disabled" - ] - }, - "LastMemberQueryInterval": { - "type": "unsignedInt", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "In IGMPv2, it sets the interval at which a querier sends group-specific queries after receiving a leave message. In IGMPv3, it sets the interval at which a querier sends group-and-source-specific queries after receiving a report that changes multicast source and group mappings.", - "datatype": "unsignedInt", - "range": [ - { - "max": 65535 - } - ] - }, - "ImmediateLeave": { - "type": "boolean", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Enables the device to immediately remove a port from the forwarding entry for a multicast group when the port receives a leave message", - "datatype": "boolean" - }, - "FilterNumberOfEntries": { - "type": "unsignedInt", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "<>", - "datatype": "unsignedInt" - }, - "ClientGroupNumberOfEntries": { - "type": "unsignedInt", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "<>", - "datatype": "unsignedInt" - }, - "Device.{BBF_VENDOR_PREFIX}IGMP.Snooping.{i}.ClientGroup.{i}.": { - "type": "object", - "protocols": [ - "cwmp", - "usp" - ], - "description": "Contain entries of clients associated with a multicast stream", - "access": false, - "array": true, - "GroupAddress": { - "type": "string", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "IP address of the multicast stream to which clients are listening to", - "datatype": "string" - }, - "AssociatedDeviceNumberOfEntries": { - "type": "unsignedInt", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "<>", - "datatype": "unsignedInt" - }, - "Device.{BBF_VENDOR_PREFIX}IGMP.Snooping.{i}.ClientGroup.{i}.AssociatedDevice.{i}.": { - "type": "object", - "protocols": [ - "cwmp", - "usp" - ], - "description": "Table contain details of the client devices which has joined this multicast stream, contains its IP address, the CPE interface to which it is connected to and a timeout value which is the time since this device sent the last join", - "access": false, - "array": true, - "Interface": { - "type": "string", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Identifier of the Ethernet interface in the device. This parameter can be an entry in the table <.>>.", - "datatype": "string" - }, - "Host": { - "type": "string", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Identifier of the Host associated with the device. This parameter can be an entry in the table <.>>.", - "datatype": "string" - }, - "Timeout": { - "type": "unsignedInt", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Time since last join, if this elapses streaming shall stop", - "datatype": "unsignedInt" - } - } - }, - "Device.{BBF_VENDOR_PREFIX}IGMP.Snooping.{i}.Filter.{i}.": { - "type": "object", - "protocols": [ - "cwmp", - "usp" - ], - "description": "Filter out the multicast stream with the IP Adddress specified in Filter.{i}.IPAddress", - "access": true, - "array": true, - "Enable": { - "type": "boolean", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Enables this filter instance", - "datatype": "boolean" - }, - "IPAddress": { - "type": "string", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Filter out the multicast stream based on IPAddress", - "datatype": "IPAddress", - "range": [ - { - "max": 45 - } - ] - } - } - }, - "Device.{BBF_VENDOR_PREFIX}IGMP.Proxy.{i}.": { - "type": "object", - "protocols": [ - "cwmp", - "usp" - ], - "description": "Multicast table with proxied instances", - "access": true, - "array": true, - "Enable": { - "type": "boolean", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Indicates whether or not the proxy is enabled.", - "datatype": "boolean" - }, - "Version": { - "type": "string", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Indicates the version of the IGMP", - "datatype": "string", - "enumerations": [ - "V2", - "V3" - ] - }, - "Robustness": { - "type": "unsignedInt", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Number of times for retransmitting IGMP queries in case of packet loss. A higher robustness variable makes the IGMP querier more robust.", - "datatype": "unsignedInt", - "range": [ - { - "max": 65535 - } - ] - }, - "Aggregation": { - "type": "boolean", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "This feature enables the device to forward only the first IGMP report for a multicast group to its directly connected Layer 3 device", - "datatype": "boolean" - }, - "QueryInterval": { - "type": "unsignedInt", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "The Query Interval is the interval between General Queries sent by the Querier.", - "datatype": "unsignedInt", - "range": [ - { - "max": 65535 - } - ] - }, - "QueryResponseInterval": { - "type": "unsignedInt", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Specify how long the querier routing device waits to receive a response to a host-query message from a host.", - "datatype": "unsignedInt", - "range": [ - { - "max": 65535 - } - ] - }, - "LastMemberQueryInterval": { - "type": "unsignedInt", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "In IGMPv2, it sets the interval at which a querier sends group-specific queries after receiving a leave message. In IGMPv3, it sets the interval at which a querier sends group-and-source-specific queries after receiving a report that changes multicast source and group mappings.", - "datatype": "unsignedInt", - "range": [ - { - "max": 65535 - } - ] - }, - "ImmediateLeave": { - "type": "boolean", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Enable the device to leave the multicast group immediately after the last host leaves the multicast group", - "datatype": "boolean" - }, - "FilterNumberOfEntries": { - "type": "unsignedInt", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "<>", - "datatype": "unsignedInt" - }, - "ClientGroupNumberOfEntries": { - "type": "unsignedInt", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "<>", - "datatype": "unsignedInt" - }, - "InterfaceNumberOfEntries": { - "type": "unsignedInt", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "<>", - "datatype": "unsignedInt" - }, - "Device.{BBF_VENDOR_PREFIX}IGMP.Proxy.{i}.ClientGroup.{i}.": { - "type": "object", - "protocols": [ - "cwmp", - "usp" - ], - "description": "Contain entries of clients associated with a multicast stream", - "access": false, - "array": true, - "GroupAddress": { - "type": "string", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "IP address of the multicast stream to which clients are listening to", - "datatype": "string" - }, - "AssociatedDeviceNumberOfEntries": { - "type": "unsignedInt", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "<>", - "datatype": "unsignedInt" - }, - "Device.{BBF_VENDOR_PREFIX}IGMP.Proxy.{i}.ClientGroup.{i}.AssociatedDevice.{i}.": { - "type": "object", - "protocols": [ - "cwmp", - "usp" - ], - "description": "#same as Snooping associated device#", - "access": false, - "array": true, - "Interface": { - "type": "string", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Identifier of the Ethernet interface in the device. This parameter can be an entry in the table <.>>.", - "datatype": "string" - }, - "Host": { - "type": "string", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Identifier of the Host associated with the device. This parameter can be an entry in the table <.>>.", - "datatype": "string" - }, - "Timeout": { - "type": "unsignedInt", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Time since last join, if this elapses streaming shall stop", - "datatype": "unsignedInt" - } - } - }, - "Device.{BBF_VENDOR_PREFIX}IGMP.Proxy.{i}.Filter.{i}.": { - "type": "object", - "protocols": [ - "cwmp", - "usp" - ], - "description": "Filter table for multicast proxy", - "access": true, - "array": true, - "Enable": { - "type": "boolean", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Enables this filter instance", - "datatype": "boolean" - }, - "IPPrefix": { - "type": "string", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Filter out the multicast stream based on IPAddress", - "datatype": "string" - } - }, - "Device.{BBF_VENDOR_PREFIX}IGMP.Proxy.{i}.Interface.{i}.": { - "type": "object", - "protocols": [ - "cwmp", - "usp" - ], - "description": "Interfaces associated with proxy", - "access": true, - "array": true, - "Interface": { - "type": "string", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Identifier of the IP interface in the device. This parameter can be an entry in the table <.>>.", - "datatype": "string", - "range": [ - { - "max": 256 - } - ] - }, - "Upstream": { - "type": "boolean", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "true if interface is upstream, else downstream. usually the lan facing is downstream and wan facing is upstream", - "datatype": "boolean" - }, - "SnoopingMode": { - "type": "string", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "defines how the unknown multicast are treated on the snooped interface. Standard means forward the unknown stream, blocking means block the unknown stream and disabled mean disable snooping", - "datatype": "string", - "enumerations": [ - "Standard", - "Blocking", - "Disabled" - ] - } - } - } - }, - "Device.{BBF_VENDOR_PREFIX}MLD.": { - "type": "object", - "protocols": [ - "cwmp", - "usp" - ], - "description": "Object contains parameters related to MLD settings for IPTV service", - "access": false, - "array": false, - "SnoopingNumberOfEntries": { - "type": "unsignedInt", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "<>", - "datatype": "unsignedInt" - }, - "ProxyNumberOfEntries": { - "type": "unsignedInt", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "<>", - "datatype": "unsignedInt" - }, - "Device.{BBF_VENDOR_PREFIX}MLD.Snooping.{i}.": { - "type": "object", - "protocols": [ - "cwmp", - "usp" - ], - "description": "#same as snooping object#", - "access": true, - "array": true, - "Enable": { - "type": "boolean", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Indicates whether or not the MLD snooping is enabled.", - "datatype": "boolean" - }, - "Version": { - "type": "string", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Indicates the version of MLD", - "datatype": "string", - "enumerations": [ - "V1", - "V2" - ] - }, - "Robustness": { - "type": "unsignedInt", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Number of times for retransmitting MLD queries in case of packet loss. A higher robustness variable makes the MLD querier more robust.", - "datatype": "unsignedInt", - "range": [ - { - "max": 65535 - } - ] - }, - "Aggregation": { - "type": "boolean", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "This enables the device to forward only the first MLD report for a multicast group to its directly connected Layer 3 device", - "datatype": "boolean" - }, - "Interface": { - "type": "string", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Path of object on which to snoop, usually a bridge", - "datatype": "string" - }, - "Mode": { - "type": "string", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Multicast snooping mode, when defined as standard, unknown stream flooded on all ports of the bridge, when defined as blocking unknown streams dropped it, when defined as disabled it disabled the multicast traffic.", - "datatype": "string", - "enumerations": [ - "Standard", - "Blocking", - "Disabled" - ] - }, - "LastMemberQueryInterval": { - "type": "unsignedInt", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "In MLDv1, it sets the interval at which a querier sends group-specific queries after receiving a leave message. In MLDv2, it sets the interval at which a querier sends group-and-source-specific queries after receiving a report that changes multicast source and group mappings.", - "datatype": "unsignedInt", - "range": [ - { - "max": 65535 - } - ] - }, - "ImmediateLeave": { - "type": "boolean", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Enables the device to immediately remove a port from the forwarding entry for a multicast group when the port receives a leave message", - "datatype": "boolean" - }, - "FilterNumberOfEntries": { - "type": "unsignedInt", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "<>", - "datatype": "unsignedInt" - }, - "Device.{BBF_VENDOR_PREFIX}MLD.Snooping.{i}.Filter.{i}.": { - "type": "object", - "protocols": [ - "cwmp", - "usp" - ], - "description": "Filter out the multicast stream with the IP Adddress specified in Filter.{i}.IPAddress", - "access": true, - "array": true, - "Enable": { - "type": "boolean", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Enables this filter instance", - "datatype": "boolean" - }, - "IPAddress": { - "type": "string", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Filter out the multicast stream based on IPAddress", - "datatype": "IPAddress", - "range": [ - { - "max": 45 - } - ] - } - } - }, - "Device.{BBF_VENDOR_PREFIX}MLD.Proxy.{i}.": { - "type": "object", - "protocols": [ - "cwmp", - "usp" - ], - "description": "Multicast table with proxied instances", - "access": true, - "array": true, - "Enable": { - "type": "boolean", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Indicates whether or not the proxy is enabled.", - "datatype": "boolean" - }, - "Version": { - "type": "string", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Indicates the version of the MLD", - "datatype": "string", - "enumeration": [ - "V1", - "V2" - ] - }, - "Robustness": { - "type": "unsignedInt", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Number of times for retransmitting MLD queries in case of packet loss. A higher robustness variable makes the MLD querier more robust.", - "datatype": "unsignedInt", - "range": [ - { - "max": 65535 - } - ] - }, - "Aggregation": { - "type": "boolean", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "This feature enables the device to forward only the first MLD report for a multicast group to its directly connected Layer 3 device", - "datatype": "boolean" - }, - "QueryInterval": { - "type": "unsignedInt", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "The Query Interval is the interval between General Queries sent by the Querier.", - "datatype": "unsignedInt", - "range": [ - { - "max": 65535 - } - ] - }, - "QueryResponseInterval": { - "type": "unsignedInt", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Specify how long the querier routing device waits to receive a response to a host-query message from a host.", - "datatype": "unsignedInt", - "range": [ - { - "max": 65535 - } - ] - }, - "LastMemberQueryInterval": { - "type": "unsignedInt", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "In MLDv1, it sets the interval at which a querier sends group-specific queries after receiving a leave message. In MLDv2, it sets the interval at which a querier sends group-and-source-specific queries after receiving a report that changes multicast source and group mappings.", - "datatype": "unsignedInt", - "range": [ - { - "max": 65535 - } - ] - }, - "ImmediateLeave": { - "type": "boolean", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Enable the device to leave the multicast group immediately after the last host leaves the multicast group", - "datatype": "boolean" - }, - "FilterNumberOfEntries": { - "type": "unsignedInt", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "<>", - "datatype": "unsignedInt" - }, - "InterfaceNumberOfEntries": { - "type": "unsignedInt", - "read": true, - "write": false, - "protocols": [ - "cwmp", - "usp" - ], - "description": "<>", - "datatype": "unsignedInt" - }, - "Device.{BBF_VENDOR_PREFIX}MLD.Proxy.{i}.Interface.{i}.": { - "type": "object", - "protocols": [ - "cwmp", - "usp" - ], - "description": "Interfaces associated with proxy", - "access": true, - "array": true, - "Interface": { - "type": "string", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Identifier of the IP interface in the device. This parameter can be an entry in the table <.>>.", - "datatype": "string", - "range": [ - { - "max": 256 - } - ] - }, - "Upstream": { - "type": "boolean", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "true if interface is upstream, else downstream. usually the lan facing is downstream and wan facing is upstream", - "datatype": "boolean" - }, - "SnoopingMode": { - "type": "string", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "defines how the unknown multicast are treated on the snooped interface. Standard means forward the unknown stream, blocking means block the unknown stream and disabled mean disable snooping", - "datatype": "string", - "enumerations": [ - "Standard", - "Blocking", - "Disabled" - ] - } - }, - "Device.{BBF_VENDOR_PREFIX}MLD.Proxy.{i}.Filter.{i}.": { - "type": "object", - "protocols": [ - "cwmp", - "usp" - ], - "description": "Filter table for multicast proxy", - "access": true, - "array": true, - "Enable": { - "type": "boolean", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Enables this filter instance", - "datatype": "boolean" - }, - "IPAddress": { - "type": "string", - "read": true, - "write": true, - "protocols": [ - "cwmp", - "usp" - ], - "description": "Filter out the multicast stream based on IPAddress", - "datatype": "IPAddress", - "range": [ - { - "max": 45 - } - ] - } - } - } } } } diff --git a/tools/bbf_common.py b/tools/bbf_common.py index a5e40d80..6345597f 100755 --- a/tools/bbf_common.py +++ b/tools/bbf_common.py @@ -364,6 +364,7 @@ def download_and_build_plugins(plugins, vendor_prefix): dm_files = get_option_value(plugin, "dm_files") is_microservice = get_option_value(plugin, "is_microservice") extra_dependencies = get_option_value(plugin, "extra_dependencies", []) + dm_desc_file = get_option_value(plugin, "dm_info_file", "") repo_path = None name=os.path.basename(repo).replace('.git','') @@ -392,7 +393,12 @@ def download_and_build_plugins(plugins, vendor_prefix): if repo_path is None: print("Repository path not defined!!!") BBF_ERROR_CODE += 1 - continue + continue + + create_folder(".repo/dm_info") + if dm_desc_file.endswith('.json'): + dest_file = ".repo/dm_info/" + os.path.basename(dm_desc_file).replace('.json', f"_{plugin_index}.json") + rename_file(repo_path + "/" + dm_desc_file, dest_file) LIST_FILES = [] os.chdir(repo_path) diff --git a/tools/generate_dm.py b/tools/generate_dm.py index 06c0615a..a0653adf 100755 --- a/tools/generate_dm.py +++ b/tools/generate_dm.py @@ -8,6 +8,7 @@ import json import bbf_common as bbf import generate_dm_xml as bbf_xml import generate_dm_excel as bbf_excel +import glob def print_dm_usage(): @@ -96,7 +97,14 @@ else: output_dir = bbf.get_option_value(OUTPUT, "output_dir", "./out") bbf.create_folder(output_dir) - + + print("Dumping default DM_JSON_FILES") + print(DM_JSON_FILES) + DM_JSON_FILES.extend(glob.glob('.repo/dm_info/*.json')) + print("Dumping all") + print(DM_JSON_FILES) + + if isinstance(file_format, list): for _format in file_format: diff --git a/tools/tools_input.json b/tools/tools_input.json index a5418ccc..172d8891 100644 --- a/tools/tools_input.json +++ b/tools/tools_input.json @@ -128,7 +128,8 @@ "version": "devel", "dm_files": [ "src/times.c" - ] + ], + "dm_info_file": "src/datamodel_description.json" }, { "repo": "https://dev.iopsys.eu/bbf/timemngr.git", @@ -211,6 +212,7 @@ "repo": "https://dev.iopsys.eu/hal/ethmngr.git", "proto": "git", "version": "devel", + "dm_info_file": "bbf_plugin/datamodel_description.json", "dm_files": [ "bbf_plugin/ethernet.c", "bbf_plugin/dmlayer.c" @@ -240,6 +242,7 @@ "repo": "https://dev.iopsys.eu/network/bridgemngr.git", "proto": "git", "version": "devel", + "dm_info_file": "src/driver_vlan_backend/datamodel_description.json", "dm_files": [ "src/driver_vlan_backend/bridging.c", "src/driver_vlan_backend/common.c" @@ -311,6 +314,7 @@ "repo": "https://dev.iopsys.eu/hal/mcastmngr.git", "proto": "git", "version": "devel", + "dm_info_file": "bbf_plugin/datamodel_description.json", "dm_files": [ "bbf_plugin/mcast_bbf.c", "bbf_plugin/x_iopsys_eu_igmp.c", @@ -321,6 +325,7 @@ "repo": "https://dev.iopsys.eu/voice/tr104.git", "proto": "git", "version": "devel", + "dm_info_file": "libdm/extensions/iowrt/datamodel_description.json", "dm_files": [ "libdm/tr104/*.c" ], diff --git a/utilities/README.md b/utilities/README.md new file mode 100644 index 00000000..7e3fa85b --- /dev/null +++ b/utilities/README.md @@ -0,0 +1,80 @@ +# Utilities to support datamodel deployments + +This directory has sets of small utilities to ease the datamodel deployments and integration with higher layer application protocols. + +List of utilities: + +1. bbf.diag +2. bbf.secure +3. bbf.config + +## bbf.diag utility + +`bbf.diag` is a `rpcd` libexec based utility, which is responsible for providing ubus backend to few datamodel diagnostics commands like: + +- ipping +- nslookup +- serverselection +- udpecho + +### How to add a new bbf.diag utility + +To add a new bbf.diag utility user has to add an script with below syntax + +```bash +#!/bin/sh + +. /usr/share/libubox/jshn.sh +. /usr/share/bbfdm/scripts/bbf_api + +__list() { + json_add_object "test" + json_add_string "host" "str" + json_close_object +} + +__error() { + json_init + json_add_string "Status" "$1" +} + +__launch() { + json_init + json_add_string "Status" "$1" +} + +if [ "$1" = "list" ]; then + __list +elif [ -n "$1" ]; then + __launch "$1" +else + __error "Error_Internal" "1" +fi +``` + +User needs to install this newly added script using `BBFDM_INSTALL_SCRIPT` bbfdm.mk API. + +References: +- [Diagnostics Scripts](https://dev.iopsys.eu/bbf/tr143d/-/tree/devel/scripts/bbf_diag) +- [Installation](https://dev.iopsys.eu/feed/iopsys/-/blob/devel/tr143/Makefile) + + +## bbf.secure utility + +USP[TR369 Specifications](https://usp.technology/specification/index.html#sec:special-roles) requirement of 'SecuredRole' requires bbfdm layer to retrieve and provide the Secured(Password/key) parameter values in plain text. + +But storing Secured parameters in plain text in uci/filesystem is bit of a security risk, to mitigate the risk `bbf.secure` provides way to store the Secured parameter values in hashed format. + +A how to use guide for bbf.secure available [here](https://dev.iopsys.eu/feed/iopsys/-/tree/devel/bbfdm?ref_type=heads#bbf_obfuscation_key) + +## bbf.config utility + +OpenWRT way of reloading services with `ubus call uci commit '{"name":""}` does not perfectly fits with datamodel requirements. It send a trigger via rpcd to procd by using this ubus call which returns instantly, internally procd reloads for all the services which has a reload dependency configured on that specific uci. +Sometimes, there is a good amount of delay in trigger and actual service reload. + +Bbf.config solves that by adding an in-build reload monitoring functionality which get the list of impacted services and then monitor for PID change for the services with a timeout of 10 sec, with this we make sure Higher layer application(icwmp/obsupa) waits for the application before processing more command. + +Currently have two variants of bbf.config, which can be enabled with below compile time configs + +1. CONFIG_BBF_CONFIGMNGR_SCRIPT_BACKEND => Simple rpcd script based backend +2. CONFIG_BBF_CONFIGMNGR_C_BACKEND => C based application backend with PID monitoring (default) diff --git a/libbbfdm/scripts/bbf_activate_handler.sh b/utilities/files/usr/share/bbfdm/scripts/bbf_activate_handler.sh similarity index 100% rename from libbbfdm/scripts/bbf_activate_handler.sh rename to utilities/files/usr/share/bbfdm/scripts/bbf_activate_handler.sh diff --git a/libbbfdm/scripts/bbf_api b/utilities/files/usr/share/bbfdm/scripts/bbf_api similarity index 100% rename from libbbfdm/scripts/bbf_api rename to utilities/files/usr/share/bbfdm/scripts/bbf_api diff --git a/libbbfdm/scripts/bbf_check_idle.sh b/utilities/files/usr/share/bbfdm/scripts/bbf_check_idle.sh similarity index 100% rename from libbbfdm/scripts/bbf_check_idle.sh rename to utilities/files/usr/share/bbfdm/scripts/bbf_check_idle.sh