icwmp/docs/arch/design.md

Design of icwmpd (TR069 client)

icwmpd is a client side implementation of the CWMP protocol. It's in conformance with all the required features described in the TR-069 standard. It supports TR-069 features like cwmp session management, events management, SOAP management, RPC methods management etc.

Source file tree as per CWMP Stack

As described in TR-069 standard, the CWMP stack comprises several components that are unique to this protocol, and makes use of several standard protocols:

Feature	Source file(s)	Description
Application	cwmp.c, session.c	cwmp client implementation based on libubox's uloop functionality
RPC Methods	rpc.c	Handling of both acs and cwmp rpc methods as defined in TR069
SOAP	xml.c	A standard XML-based syntax used here to encode remote procedure calls along with SOAP handling
HTTP	http.c, digauth.c	Responsible to send SOAP messages over HTTP using libcurl library.
SSL/TLS	ssl_utils.c	Provides SSL/TLS functionality over HTTP with OpenSSL/mbedtls/wolfssl

Common source files
backup_session.c
cwmp_uci.c
ubus_utils.c
subprocess.c
common.c
config.c
datamodel_interface.c
diagnostic.c
download.c
upload.c
notifications.c

Main structure of icwmp app

icwmpd main context stored in cwmp global structure, the following schema presents this structure with the most important attributes:

classDiagram
class cwmp {
	conf: struct config
	deviceid: struct deviceid
	session: struct session
	heart_session: bool
	diag_session: bool
	event_id: int
	cr_socket_desc: int
	pid_file: FILE
}

Item	Type	Description	Comment
conf	config structure	config structure is responsible for defining the UCI configuration of the application. It is loaded in the start of icwmp.	Multiple UCI options are defined in this structure such as configurations related to the CPE like CR credentials, CR port, provisioning code and configurations related to the ACS connection like ACS access username/password, periodic_inform_enable, periodic_inform_interval, and so on.
heart_session	boolean attribute	This attribute is used to check if the running session is a Heartbeat session.
diag_session	boolean attribute	This attribute is used to check if the running session contains the event '8 DIAGNOSTICS COMPLETE'
event_id	integer attribute	is used by the app to store the number of events in the running session.
cr_socket_des	integer attribute	This attribute contains the id of the socket used by the CR.
pide_file	File type attribute	This file used by the app in order to garantuate a single app instance running.
deviceid	deviceid structure	This struct contains the device information important attributes values. like ManufacturerOUI, Manufacturer, SerialNumber, ProductClass, SoftwareVersion.
session	session structure	This structure contains attributes related to the running session.

classDiagram
class session {
	head_rpc_acs: list
	rpc_cpe: struct rpc
	events: list
	session_status: struct session_status
	tree_in: mxml_node_t
	tree_out: mxml_node_t
	body_in: mxml_node_t
	fault_code: int
}

Session Attributes:

Item	Type	Description	Comment
rpc_cpe	struct rpc	It contains RPC method that is just requested by the ACS to be executed in the CPE.
head_rpc_acs	struct list_head	It contains RPC methods list that the CPE requests to be executed in the ACS side in the actual session.
events	struct list_head	It contains list of events that the CPE notifies the ACS in the Inform message of the actual session.
session_status	struct session_status	It contains information about the running session like start time, end time, if it's successful or failed session, hearbeat session validation, and so on.

icwmp application

The following diagram shows how icwmp application manage CWMP sessions with uloop:

flowchart TD
	A[icwmp init] --> B[uloop init]
	A --> C[CR http server init]
	B --> D{wait uloop timeout}
	D -- ubus timeout --> E[receive tr069 method call]
	D -- periodic timeout --> F[Add '2 PERIODIC' event to the list of events]
	F --> G[Execute CWMP session]
	G --> H[trigger check value change timeout]
	H --> D
	E --> I{the method is Inform}
	I -- yes --> G
	I -- no --> J[Execute the ubus method]
	J --> D
	C --> K[Start CR server thread]
	K --> L[listen to coming HTTP requests in the CR port]
	L --> M{CR is received}
	M -- yes --> N[execute the ubus method: tr069 inform]
	N --> E
	M -- no --> L

As described in the diagram, after initiating the icwmp application (config init, backup init, ...), the application trigger:

1. Some functionalities controlled/managed by using uloop timers, below are the list of timers:

• ubus methods timeout
• autonomous policy timeouts
• session timeout
• heartbeat timeout
• periodic session timeout

these timers gets initialized when the application starts then wait for the uloop timeout events.

2. A thread is created at the same time. It permits a permenant listening of the port , in the purpose to receive connection requests. In case a CR is received successfully "tr069 inform" ubus call is triggered from this thread in the purpose to trigger a new session with '6 CONNECTION REQUEST' event.

icwmp tr-069 session

CWMP session in icwmp client

Inform ACS method

The Inform ACS request is sent by the CPE to the ACS in the start of the CWMP session, in order to inform him about information like the device id, events, software version, the CR url ...

In icwmp the corresponding function responsible to create the Inform message is cwmp_rpc_acs_prepare_message_inform. It starts by getting the device ID attributes and the list of events that needs to be included in the inform message and then parameters that are amended in the ParameterList including default Inform Parameter and other parameters like parameters related to the Value Change.

Events manipulation

As described in TR069 standard, events in CWMP protocol must be sent by the CPE in an Inform request in order to notify the ACS when something of interest has happened. CWMP events are stored in the events list attribute of the session structure attribute. Each element of this list is an instance of the structure event_container that is the following:

classDiagram
class event_container {
	code: integer
	next_session: boolean
	command_key: string
	head_dm_parameter: list
	id: integer
}

When creating an inform message, the events are loaded from the events list.

Inform Events	Description of the event
0 BOOTSTRAP	Included when client connects with the ACS for the very first time
1 BOOT	When cwmp client reloads or reboots

Event associated with reboot/upgrades

Event	Description of the event
M Reboot	Reboot triggered from ACS
M Download	Reboot caused by firmware upgrade
M ScheduleDownload	Reboot caused by a scheduled firmware upgrade
7 TRANSFER COMPLETE

Runtime events, while handling RPC calls below events gets added in the list:

Event	Description of the event
3 SHEDULED	for ScheduleInform method
7 TRANSFER COMPLETE	in the call of Download, Upload
8 DIAGNOSTIC COMPLETE	after completing diagnostic execution triggered by the ACS
11 DU STATE CHANGE COMPLETE	after completing DU request execution triggered by the ACS

Periodic events:

Event	Description of the event
2 PERIODIC	Periodic inform messages
14 HEARTBEAT	Periodic heartbeat messages

External Events:

Event	Description of the event
6 CONNECTION REQUEST	when receiving a connection request from the ACS in order to start a new session.
4 VALUE CHANGE	check notifications part
10 AUTONOMOUS TRANSFER COMPLETE
12 AUTONOMOUS DU STATE CHANGE COMPLETE

Notifications

Notifications in icwmp client

XML in icwmp

XML mechanism in icwmp client

Backup Session management

The backup session feature in icwmp is used to store data that should be conserved even after reboot or system upgrade:

• events
• download
• transfer complete
• schedule download
• schedule inform
• upload
• change du state
• autonomous change du state
• du state change complete

This data is stored in xml format in the file /etc/icwmpd/icwmpd_backup_session.xml.

The data is loaded by calling the function cwmp_load_saved_session at the start of the icwmp application.

The backup session feature uses XML functions (check XML part) to build/load XML nodes that should be stored in the backup session file.

For each kind of backup session data there are rows in xml_nodes_data. Their indexes are defined in the enumeration xml_node_references.

All backup session indexes are successive in the enumeration and starts with BKP_.

For each kind of backup session data, there are insert functions that call build_xml_node_data and load functions that calls load_xml_node_data.

UCI and config mangement

• UCI
• UBUS