bbfdm/docs/guide/libbbfdm-ubus.md

LIBBBFDM Ubus (libbbfdm-ubus)

libbbfdm-ubus is a library that provides APIs to expose datamodel over ubus. It is used to manage various data models in different micro-services and higher-level applications.

Use Cases

libbbfdm-ubus library can be used by:

• bbfdmd: to expose the core data model
• dm-service: to expose a sub-data model as micro-service, example: Netmngr
• Higher-level applications(unified daemon): to expose custom data models as microservices within their daemon, example: Timemngr

libbbfdm-ubus APIs

The following APIs are provided by libbbfdm-ubus to expose data model over ubus:

bbfdm_ubus_regiter_init

This method is used to initialize the bbfdm_context structure object and register ubus data model methods.

int bbfdm_ubus_regiter_init(struct bbfdm_context *bbfdm_ctx)

inputs
	struct bbfdm_context *bbfdm_ctx
		pointer to struct bbfdm_context structure to be initialized.

return
	int fault
		returns 0 on success, or an error code if the registration fails.	

bbfdm_ubus_regiter_free

This method is used to free the bbfdm_context structure object

int bbfdm_ubus_regiter_free(struct bbfdm_context *bbfdm_ctx)

inputs
	struct bbfdm_context *bbfdm_ctx
		pointer to struct bbfdm_context structure to be freed.

return
	int fault
		returns 0 on success, or an error code if freeing fails.	

bbfdm_ubus_set_service_name

This method is used the service name for the daemon running as a microservice

void bbfdm_ubus_set_service_name(struct bbfdm_context *bbfdm_ctx, const char *srv_name)

input
	struct bbfdm_context *bbfdm_ctx
		pointer to struct bbfdm_context structure

	const char *srv_name
		pointer to service name to set
	
return
	None

bbfdm_ubus_set_log_level

This method is used to set the log level according to the standard syslog levels

void bbfdm_ubus_set_log_level(int log_level)

input
	int log_level
		desired log level to set
	
return
	None

bbfdm_ubus_load_data_model

This method is used to load an internal data model, allowing you to use an internal model instead of external plugins (e.g., DotSo or JSON).

void bbfdm_ubus_load_data_model(DM_MAP_OBJ *DynamicObj)

input
	DM_MAP_OBJ *DynamicObj
		pointer to internal data model
	
return
	None

libbbfdm-ubus methods

Following are the ubus methods exposed by libbbfdm-ubus when registering a new module:

# ubus -v list bbfdm
bbfdm' @b93b62aa
    "get":{"path":"String","paths":"Array","maxdepth":"Integer","optional":"Table"}
    "schema":{"path":"String","paths":"Array","first_level":"Boolean","optional":"Table"}
    "instances":{"path":"String","paths":"Array","first_level":"Boolean","optional":"Table"}
    "set":{"path":"String","value":"String","datatype":"String","obj_path":"Table","optional":"Table"}
    "operate":{"command":"String","command_key":"String","input":"Table","optional":"Table"}
    "add":{"path":"String","obj_path":"Table","optional":"Table"}
    "del":{"path":"String","paths":"Array","optional":"Table"}
    "notify_event":{"name":"String","input":"Array"}
    "service":{}

libbbfdm-ubus example(s)

1. The requested value is correct as per TR181 standard, but there is a limitation in the device.

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.

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.

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."

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, users can add such fault message using bbfdm_set_fault_message libbbfdm-api's API, if no specific fault message defined for particular obj/param, datamodel returns standard error messages that are defined in CWMP and USP protocols as the fault message value.

Fault handling

To indicate a fault and source of fault, libbbfdm-ubus provides fault along with fault_msg in the response in case of faults, which then handled by higher layer applications (i.e icwmp, obuspa).

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).

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

example(s):

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:~#