mirror/icwmp
1
0
Fork 0
mirror of https://dev.iopsys.eu/bbf/icwmp.git synced 2025-12-10 07:44:41 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

doc: Language fixes and tables

Browse source
This commit is contained in:
Andreas Jonson 2023-03-23 11:18:01 +00:00 • committed by Vivek Kumar Dutta
parent cac51033b4
commit 790706f578
12 changed files with 212 additions and 172 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
README.md
View file

@ -37,7 +37,10 @@ config lwn 'lwn'
option port ''
```
> Note: `icwmpd` depends on usp.raw for all datamodel parameters, some `DeviceId` related parameters can be overwritten by writing them directly on `/etc/config/cwmp` file.
!!! note
`icwmpd` depends on usp.raw for all datamodel parameters, some `DeviceId` related parameters can be overwritten by writing them directly on `/etc/config/cwmp` file.
```bash
uci set cwmp.cpe.manufacturer="ABC"
@ -49,9 +52,12 @@ uci set cwmp.cpe.model_name="MODELXXX"
uci set cwmp.cpe.description="This is a test device"
uci commit cwmp
```
> Complete UCI for `cwmp` configuration available in [link](./docs/api/uci/cwmp.md) or [raw schema](https://dev.iopsys.eu/iopsys/icwmp/-/blob/devel/schemas/uci/cwmp.json)
> icwmpd gets the datamodel from the DUT via ubus using uspd, and also it registers `tr069` ubus namespace to expose some debug and cwmp client rpc funtionalities, so it is required to start it after starting `ubusd` and `uspd`.
!!! note
Complete UCI for `cwmp` configuration available in [link](./docs/api/uci/cwmp.md) or [raw schema](https://dev.iopsys.eu/iopsys/icwmp/-/blob/devel/schemas/uci/cwmp.json)
icwmpd gets the datamodel from the DUT via ubus using uspd, and also it registers `tr069` ubus namespace to expose some debug and cwmp client rpc funtionalities, so it is required to start it after starting `ubusd` and `uspd`.
## Important topics
* [icwmp design](./docs/arch/design.md)

271
docs/arch/design.md
View file

@ -1,101 +1,41 @@
# Design of icwmp tr-069 client
# 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 |
## General Description
icwmp is client side implementation of CWMP protocol. Its source code is completely conform with TR-069 standard. So it supports all required features described in the TR-069 standard.
So TR-069 features like cwmp session, events management, soap management, RPC methods management ... are supportd in the icwmp implementation.
| 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 |
As descibed in TR-069 standard, CWMP stack comprises several components that are unique to this protocol, and makes use of several standard protocols.
Those components are the following:
### CWMP Stack and icwmp corresponding source files
<table>
<tbody>
<tr><td>
<table>
<thead>
<tr>
<th colspan="2">CWMP Stack and icwmp corresponding source files</th>
</tr>
</thead>
<tbody>
<tr><td><b>Application</b></td><td> cwmp.c session.c</td></tr>
<tr><td><b>RPC Methods</b></td><td> rpc.c</td></tr>
<tr><td><b>SOAP</b></td><td>xml.c</td></tr>
<tr><td><b>HTTP</b></td><td>http.c digauth.c</td></tr>
<tr><td><b>SSL/TLS</b></td><td> ssl_utils.c</td></tr>
</tbody>
</table>
</td>
<td>
<table>
<thead>
<tr>
<th>Common Source files</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tg-0pky">backup_session.c</td>
</tr>
<tr>
<td class="tg-0pky">cwmp_uci.c</td>
</tr>
<tr>
<td class="tg-0pky">ubus_utils.c</td>
</tr>
<tr>
<td class="tg-0pky">subprocess.c</td>
</tr>
<tr>
<td class="tg-0pky">common.c</td>
</tr>
<tr>
<td class="tg-0pky">config.c</td>
</tr>
<tr>
<td class="tg-0pky">datamodel_interface.c</td>
</tr>
<tr>
<td class="tg-0pky">diagnostic.c</td>
</tr>
<tr>
<td class="tg-0pky">download.c</td>
</tr>
<tr>
<td class="tg-0pky">upload.c</td>
</tr>
<tr>
<td class="tg-0pky">notifications.c</td>
</tr>
</tbody>
</table>
</td></tr>
</tbody>
</table>
- Application: the application uses CWMP protocol on the CPE. In the icwmp client, the main application is defined in cwmp.c source file. It's based on uloop libubox functionality. Multiple timers are running under the main uloop of icwmp like session timer, ubus timer, heartbeat timer, ...
- RPC methods: The specific RPC methods that are defined by CWMP protocol. In icwmp client RPC methods are defined under the source file rpc.c.
- SOAP: A standard XML-based syntax used here to encode remote procedure calls. The SOAP part is developed in xml.c file.
- HTTP: this part is responsible to send SOAP messages over HTTP. In icwmp it's based on libcurl library. Its corresponding C functions are developed in the file http.c.
- SSL/TLS: The standard Internet transport layer security protocol. icwmp can work with openssl or mbedtls or wolfssl depending on the SSL library selection. Its corresponding functions are defined in ssl_utils.c file.
## Main structure of icwmp app
The main structure in icwmp is the cwmp structure. Just one instance of cwmp structure is needed for the executing icwmp app.
The following schema presents this sctructure with the most important attributes:
```mermaid
`icwmpd` main context stored in cwmp global structure, the following schema presents this structure with the most important attributes:
```mermaid
classDiagram
class cwmp {
conf: struct config
@ -107,17 +47,22 @@ class cwmp {
cr_socket_desc: int
pid_file: FILE
}
```
- conf: its type is the config structure. config structure is responsible to define the UCI configuration of the application and it's 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 ...
- heart_session: is a boolean attribute. This attribute is used to check if the running session is a Heartbeat session.
- diag_session: is a boolean attribute. This attribute is used to check if the running session contains the event '8 DIAGNOSTICS COMPLETE'
- event_id: is an integer attribute, and is used by the app to store the number of events in the running session.
- cr_socket_des: is an integer attribute. This attribute contains the id of the socket used by the CR.
- pide_file: is a File type attribute. This file used by the app in order to garantuate a single app instance running.
- deviceid: its type is deviceid structure. This struct contains the device information important attributes values: OUI, Manufacturer, SerialNumber, ProductClass, SoftwareVersion.
- session: its type is session structure. This structure contains attributes related to the running session.
| 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. ||
```mermaid
classDiagram
class session {
@ -132,17 +77,20 @@ class session {
}
```
session attributes are:
- rpc_cpe: its type is struct rpc. It contains RPC method that is just requested by the ACS to be executed in the CPE.
- head_rpc_acs: its type is struct list_head. It contains RPC methods list that the CPE requests to be executed in the ACS side in the actual session.
- events: its type is struct list_head. It contains list of events that the CPE notifies the ACS in the Inform message of the actual session.
- session_status: its type is struct session_status. it contains informations about the running session like start time, end time, if it's successful or failed session, hearbeat session validation ...
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:
The following diagram shows how icwmp application manage CWMP sessions with uloop:
```mermaid
flowchart TD
A[icwmp init] --> B[uloop init]
@ -166,20 +114,20 @@ flowchart TD
```
As described in the diagram, after initiating the icwmp application (config init, backup init, ...), the application trigger:
1 - uloop initiation by initiating the following timeouts:
- ubus methods timeout
- autonomous policy timeouts
- session timeout
- heartbeat timeout
- periodic session timeout
then the application start the uloop run by waiting uloop timeouts to come.
As described in the diagram, after initiating the icwmp application (config init, backup init, ...), the application trigger:
2 - In the same time a thread is created. 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.
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
@ -188,15 +136,15 @@ In case a CR is received successfully "tr069 inform" ubus call is triggered from
## 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 some informations like the device id, events, software version, the CR url ...
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.
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:
CWMP events are stored in the **events** list_head attribute of the session structure attribute. Each element of this list is an instance of the structure event_container that is the following:
```mermaid
classDiagram
@ -209,15 +157,47 @@ class event_container {
}
```
In icwmp when creating the inform message events are loaded from **events** list.
When creating an inform message, the events are loaded from the **events** list.
As soon as the event is reached, it's added to the list events. Different scenarios are presents to reach event in icwmp:
| 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 |
- Start app events: this scenario includes following events: "0 BOOTSTRAP" (if it's the first Inform to be sent to the specified ACS), "1 BOOT".
- Get the event from the backupSession in the start of the App: Just after starting the icwmp app in the init step, the app loads the backupsession events in events list from "cwmp_event" xml tag. Then add the to the events list. This case includes events that occurs before the restart of the icwmp or reboot/upgrade of the system. In this scenario events included are: "M Reboot", "M Download", "M ScheduleDownload", "7 TRANSFER COMPLETE".
- Events when running CWMP session. Events for this scenario are detected and added to the events while executing the CWMP session especially in RPC calls. Such as "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 CDU request execution triggered by the ACS), "M Download", "M Upload" ...
- Events are detected at specific time using uloop_timeout_set:"2 PERIODIC", "14 HEARTBEAT"
- External Events: "6 CONNECTION REQUEST" when receiving a connection request from the ACS in order to start a new session. CR thread is permenantly listening on the CR port in order to detect such event and then trigger a new session. "4 VALUE CHANGE" (check notifications part), "10 AUTONOMOUS Single TRANSFER COMPLETE", "12 AUTONOMOUS DU STATE CHANGE COMPLETE"
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
@ -229,7 +209,7 @@ As soon as the event is reached, it's added to the list events. Different scenar
## Backup Session management
Backup session feature in icwmp is used to store data that should be conserved even after reboot or sysupgrad of the system. Those data are followings:
The backup session feature in icwmp is used to store data that should be conserved even after reboot or system upgrade:
- events
- download
@ -241,16 +221,19 @@ Backup session feature in icwmp is used to store data that should be conserved e
- autonomous change du state
- du state change complete
Those data are stored in xml format in the file /etc/icwmpd/icwmpd_backup_session.xml. This data is loaded by the call of the function cwmp_load_saved_session in the start of the icwmp application.
This data is stored in xml format in the file `/etc/icwmpd/icwmpd_backup_session.xml`.
Backup session feature uses XML functions (check XML part) to build/load XML nodes that should be stored in the backup session file. So for each kind of backup session datas there are rows in **xml_nodes_data** that their index are definde in the enumaration **xml_node_references**.
All backup session indexes are successive in the enumaration and starts with "BKP_".
The data is loaded by calling the function `cwmp_load_saved_session` at the start of the icwmp application.
For each kind of backup session data, there are insert functions that calls build_xml_node_data and load functions that calls load_xml_node_data.
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
**TODO**
- [UCI](./docs/api/uci/cwmp.md)
- [UBUS](./docs/api/uci/tr069.md)

15
docs/arch/notifications.md
View file

@ -15,7 +15,8 @@ Seven possible uci list can be present under the notifications section: disable
cwmp_set_parameter_attributes is the C function that is executed in case the SetParameterAttributes is called by the ACS. Its activity diagram is the following:
```mermaid
```mermaid
flowchart TD
A[Check valid parameter_name] --> B{fault?}
B -- no --> C{parameter_name is forced notification}
@ -35,7 +36,8 @@ As a first step the SPA function check if the parameter path is valid, then it c
The following decribe the algorithm of the function **update_notifications_list**:
```mermaid
```mermaid
flowchart TD
A[Iterate notifications list => param_iter notif_iter] --> B{param_name == param_iter <br> && <br> notification != notif_iter}
B -- no --> C{param_iter is suboject of param_name}
@ -60,7 +62,8 @@ false value is affected to update_ret only if the parameter_name parameter is su
cwmp_get_parameter_attributes is the C function that is executed in case the GetParameterAttributes is called by the ACS. Its input argument is the requester parameter name: param_name. Its activity diagram is the following:
```mermaid
```mermaid
flowchart TD
A[check valid parameter path of param_name] --> B{valid?}
B -- yes --> C[get_parameter_family_notifications of param_name => ret_notif, children_notif]
@ -82,7 +85,8 @@ flowchart TD
As a first step the GPA function check if the parameter path is valid, after that it calls the function get_parameter_family_notifications that has the below algorithm. This function permits to get the list of all childs parameters notifications of parameter_name presents in uci notifications list. Its input argument is the requester parameter name: param_name.
```mermaid
```mermaid
flowchart TD
A[iterate parameters_notifications list => param_iter notif_iter] --> B{param_name is subobject of param_iter <br> or param_name == param_iter}
B -- no --> C{param_iter is subobject of param_name}
@ -116,7 +120,8 @@ Next sections describes those two features in notifications in icwmp:
check_value_change is responsible to detect what parameters (with enabled notifications) values changed. This process algorithm is described in the following diagram
```mermaid
```mermaid
flowchart TD
A[get all leaf parameters values list corresponding <br>to parameters with enabled notification <br> => list_notify_params] -->B
B[parse dm_enabled_notify_file line by line]--param_json_obj-->C[get corresponding parameter/value from param_json_obj]

11
docs/arch/session.md
View file

@ -2,7 +2,8 @@
In icwmp client, the CWMP session is executed under a uloop timeout handler that calls the C function responsible on the CWMP session execution: start_cwmp_session that has the following activity diagram:
```mermaid
```mermaid
flowchart TD
A[init cwmp session] --> B[check notification value change]
B --> C{value change?}
@ -48,6 +49,7 @@ RPC ACS methods are called just after initiating the session. It starts by the c
In icwmp RPC ACS methods are defined in the array rpc_acs_methods of the structure rpc_acs_method.
```mermaid
classDiagram
class rpc_acs_method {
@ -56,12 +58,14 @@ class rpc_acs_method {
parse_message: function
}
```
- name: is a string attribute. It contains the name the RPC.
- prepare_message: it's a function attribute. This function is responsible to create the SOAP message that will be sent as the RPC method call to the ACS.
- parse_response: it's a function attribute. This function is responsible to to parse the SOAP message coming from the ACS
RPC ACS method is executed in a process respecting the tr-069 protocol layer as described in the following communication diagram:
```mermaid
graph RL
A[RPC] --> |2 related data| B[SOAP]
@ -94,6 +98,7 @@ In the next step after the CPE receive the HTTP response from the ACS, it extrac
In icwmp RPC CPE methods are defined in the array rpc_cpe_methods of the structure rpc_cpe_method.
```mermaid
classDiagram
class rpc_cpe_method {
@ -102,11 +107,13 @@ class rpc_cpe_method {
parse_message: function
}
```
- name: is a string attribute. It contains the name the RPC.
- handler: the corresponding the handler function responsible to extract data from the SOAP message and then execute corresponding features
RPC CPE method is executed in a process respecting the tr-069 protocol layer as described in the following communication diagram:
```mermaid
graph LR
A[ACS] --> |1 HTTP Request| B[HTTP]
@ -118,7 +125,7 @@ graph LR
C --> |7 Build SOAP response message| C
C --> |8 SOAP RPC response| B
B --> |9 HTTP response| A
```
```
The scenario starts by receiving the HTTP Request from the ACS. The HTTP body should be a SOAP RPC call message. The RPC method and its arguments are extracted from the SOAP message in the SOAP layer. Basing on this extracted data the corresponding function is executed in the RPC layer.

22
docs/arch/xml.md
View file

@ -8,7 +8,8 @@ All xml nodes names that are needed in icwmp for both SOAP and backup session ar
The type of the array xml_nodes_data is __xml_node_data__ :
```mermaid
```mermaid
classDiagram
class cwmp {
node_ms: integer
@ -17,12 +18,14 @@ class cwmp {
xml_tags: xml_tag array
}
```
- node_ms: is an integer that can have two values (XML_SINGLE 0 or XML_LIST 1). Is used to indicate if the corresponding XML node is present as list or just one time.
- tag_node_ref: this integer attribute is an index in the same array xml_nodes_date of the corresponding node in case of list. Its value is 0 if the component is Single.
- tag_list_name: in case of list this string is the tag parent name of each node. Its value is NULL if the component is Single.
- xml_tags: is an array of tags under the node. xml_tag is the type of this array. Its structure is the following:
```mermaid
```mermaid
classDiagram
class xml_tag {
tag_name: string
@ -31,6 +34,7 @@ class xml_tag {
xml_func: function
}
```
each xml node tag in XML mechanism developed in icwmp has as type the xml_tag structure that has presented attributes:
- tag_name: has as type string and it's the name of the tag
@ -42,7 +46,8 @@ each xml node tag in XML mechanism developed in icwmp has as type the xml_tag st
The xml_data_struct is a structure used for both load and build xml messages. It contains two parts of attributes, the first part contains attributes used for xml leaf node values for both buld and load, the second part contains attributes used while executing load/build process:
```mermaid
```mermaid
classDiagram
class xml_data_struct {
//XML node leafs attributes
@ -93,6 +98,7 @@ Single rows in the table define a node or a group of nodes that appears just on
The process of loading a single row node is done by the following algorithm:
```mermaid
flowchart TD
A[parse the requested xml node elements] -- reached_node --> B{is reached node NULL}
@ -126,7 +132,8 @@ While loading values from the XML node, the mechanism is checking the validation
Validations attribute is an array of the structure **xml_tag_validation** that has the following diagram:
```mermaid
```mermaid
classDiagram
class xml_tag_validation {
tag_name: string
@ -135,7 +142,8 @@ class xml_tag_validation {
max: integer
}
```
- tag_name: a sting that has as value the XML node tag name.
-tag_name: a sting that has as value the XML node tag name.
- validation_type: integer that its value is used to choose the suitable validation function
- min: integer used to validate if value is in a range
- max: integer used to validate if value is in a range
@ -158,6 +166,7 @@ List rows in the table **xml_nodes_data** define a node or a group of nodes tha
The process of loading a list row node is done by the following algorithm:
```mermaid
flowchart TD
A[parse the requested xml node elements] -- reached_node --> B{is reached node NULL}
@ -195,6 +204,7 @@ build_single_xml_node_data function is responsible to build XML nodes that conta
The algorithm of such feature is described in following diagram:
```mermaid
flowchart TD
A[parse xml tags array of corresponding row xml_nodes_data]-->B{End of Array?}
@ -216,6 +226,7 @@ flowchart TD
L -->M[set the opaque value to the x_node xml node]
M -->C
```
the build of a single node of xml_nodes_data array is done by the parse of the corresponding xml_tags array one by one. For each element the function creates the xml node and then set its opaque value basing on its type XML_REC, XML_FUNC, or otherwise.
#### build_xml_list_node_data
@ -224,6 +235,7 @@ build_xml_list_node_data function is responsible to build XML nodes that contain
The algorithm of such feature is described in following diagram:
```mermaid
flowchart TD
A[parse the input data_list of xml_data_struct]--list_element-->A1[create xm node element with the name tag_list_name of referenced row]

12
docs/guide/annex_f.md
View file

@ -4,6 +4,7 @@ The CPE WAN Management Protocol can be used to remotely manage CPE Devices that
> -- <cite> TR-69 Annex F.</cite>
Below is the sequence diagram for the Device-Gateway association with DHCP Discover.
```mermaid
sequenceDiagram
Lan-Device->>+Gateway: DHCP Discover (Device Identity)
@ -24,7 +25,10 @@ A Gateway here in this context means, an Annex-F capable CPE running icwmpd whic
The Gateway Identity tuple (OUI, ProductClass, SerialNumber) is present in 'db' (Same source used for Device.DeviceInfo. object).
The `/etc/init.d/icwmp` script reads the default lan interface from UCI option `cwmp.cpe.default_lan_interface` and configures the gateway identity in `dhcp` UCI for the corresponding LAN interface section to publish gateway information to its LAN clients.
> Note: If UCI option `cwmp.cpe.default_lan_interface` is not defined then gateway identity would not be published in LAN network.
!!! note
If UCI option `cwmp.cpe.default_lan_interface` is not defined then gateway identity would not be published in LAN network.
### Identification of Manageable Device in LAN network
Gateway device relies on DHCP options (/tmp/dhcp.client.options) file for getting the Manageable Device identities, which is exposed in the TR181 datamodel using (libbbf) API's.
@ -37,7 +41,10 @@ A Lan-Device here in this context means, an Annex-F capable CPE running icwmpd w
The Lan-Device Identity tuple (OUI, ProductClass, SerialNumber) is present in 'db' (Same source used for Device.DeviceInfo. object).
The `/etc/init.d/icwmp` script reads the default wan interface from UCI option `cwmp.cpe.default_wan_interface` and configures the device identity in `network` UCI to publish its own identity to upstream network (DHCP server) using DHCP option 125 for the corresponding wan interface.
> Note: If UCI option `cwmp.cpe.default_wan_interface` is not defined then it assumes the default interface as `wan`.
!!! note
If UCI option `cwmp.cpe.default_wan_interface` is not defined then it assumes the default interface as `wan`.
### Identification of Gateway Device in WAN network
If lan-device(CPE) receives DHCP option 125 in DHCP offer from upstream network it exposes the same in its UBUS method (e.g. ifstatus wan).
@ -52,6 +59,7 @@ root@iopsys-44d43771b000:~# ifstatus wan
}
}
```
ICWMPD package adds a [DHCP client hook script](https://dev.iopsys.eu/iopsys/icwmp/-/blob/devel/files/etc/udhcpc.user.d/udhcpc_icwmp_opt125.user), which parses DHCP option 125 to extract gateway identity based on Enterprise ID `3561`.
This script then writes the gateway identity in `/var/state/cwmp` if CWMP is enabled in the device.

8
docs/guide/cli.md
View file

@ -29,8 +29,11 @@ Valid commands:
del [object] => delete object
get_notif [path-expr] => get parameter notifications
```
> Note: icwmpd CLI is a debug utility and hence it is advised to use for debug and development purpose only.
> icwmpd CLI utility is independent of icwmpd daemon.
!!! note
icwmpd CLI is a debug utility and hence it is advised to use for debug and development purpose only. icwmpd CLI utility is independent of icwmpd daemon.
icwmp CLI command success result is displayed in the terminal as following:
@ -41,6 +44,7 @@ root@iopsys:~# icwmpd -c set Device.WiFi.SSID.1.SSID wifi1_ssid
Set value is successfully done
Device.WiFi.SSID.1.SSID => wifi1_ssid
```
In the case of fault the result is displayed as following:
```bash

6
docs/guide/dhcp_provisioning.md
View file

@ -11,9 +11,13 @@ root@iopsys-44d43771b000:~# ifstatus wan
}
}
```
CWMP Agent uses DHCP option 43 for provisioning if CWMP and DHCP discovery is enabled in the device. ICWMPD package adds a [DHCP client hook script](https://dev.iopsys.eu/iopsys/icwmp/-/blob/devel/files/etc/udhcpc.user.d/udhcpc_icwmp_opt43.user), which parses DHCP option 43 value to extract informations like ACS URL, minimum interval for session retry, retry interval multiplier for session retry and provisioning code that specifies the primary service provider and other provisioning information, which may be used by the ACS to determine service provider-specific customization and provisioning parameters.
This script then writes the provisioning information in `/etc/config/cwmp`.
CWMP Agent reads the provisioning information from `/etc/config/cwmp` before starting a session.
> Note: If in any time ACS configures `Device.ManagementServer.URL` then DHCP discovery is disabled automatically.
!!! note
If in any time ACS configures `Device.ManagementServer.URL` then DHCP discovery is disabled automatically.

5
docs/guide/https_config.md
View file

@ -39,7 +39,10 @@ Email Address []:dev@iopsys.eu
root@75f824228409:/opt/genieacs#
```
> Note: When generating the certificate, you must fill the Common Name filed with the correct URL server (for example here 'genieacs') otherwise you will get an error later when trying to connect to the ACS.
!!! note
When generating the certificate, you must fill the Common Name filed with the correct URL server (for example here 'genieacs') otherwise you will get an error later when trying to connect to the ACS.
## Installing and Configuring GenieACS environment variables

13
docs/guide/notification.md
View file

@ -79,7 +79,10 @@ root@iopsys:~# cat /etc/icwmpd/inform.json
}
```
> Note: In the Above example, parameter has to be defined with a valid datamodel parameter name and notify_type needs to be the notification type (number as present in the above table). Both the parameters are required.
!!! note
In the Above example, parameter has to be defined with a valid datamodel parameter name and notify_type needs to be the notification type (number as present in the above table). Both the parameters are required.
After defining the JSON file with all the required parameters, this information required to update cwmp uci as below:
@ -89,8 +92,8 @@ root@iopsys:~# uci commit cwmp
root@iopsys:~# /etc/init.d/icwmpd restart
```
>- ACS can manage the attributes of parameter added by custom_notification as it does for the other parameters
>- After firmware upgrade, for the 1st bootup, the custom_notify_json has higher priority, latter on ACS configured attributes get priority.
>- Addition of custom notification parameters is one time activity after upgrade, once done It can only be managed through ACS.
>- Parameters with wildcard not supported currently. So parameter like Device.WiFi.SSID.*. will be skipped
- ACS can manage the attributes of parameter added by custom_notification as it does for the other parameters
- After firmware upgrade, for the 1st bootup, the custom_notify_json has higher priority, latter on ACS configured attributes get priority.
- Addition of custom notification parameters is one time activity after upgrade, once done It can only be managed through ACS.
- Parameters with wildcard not supported currently. So parameter like Device.WiFi.SSID.*. will be skipped

4
docs/guide/spv_restart.md
View file

@ -8,6 +8,8 @@ Based on the response of setm_values the icwmp will do the following:
- in case of success icwmp commits the set of all parameters, without applying them so without restarting services, and then sends a success Response to the ACS including the status code 1.
- All required services(whose configuration has been modified by SPV) are restarted at the end of CWMP session in order to prevent any session interruption.
> icwmp always returns 1 as status value in case of success of SPV because all services are restarted at the end of the session.
!!! note
icwmp always returns 1 as status value in case of success of SPV because all services are restarted at the end of the session.

5
docs/guide/ubus_method.md
View file

@ -2,7 +2,10 @@
`icwmpd` provides some RPCs support over ubus and some debug utilities those can be accessed using `tr069` ubus object. So, it must be launched on startup after `ubusd`.
> Note: For more info on the `tr069` ubus schema see [link](../api/ubus/tr069.md) or [raw schema](https://dev.iopsys.eu/iopsys/icwmp/-/blob/devel/schemas/ubus/tr069.json)
!!! note
For more info on the `tr069` ubus schema see [link](../api/ubus/tr069.md) or [raw schema](https://dev.iopsys.eu/iopsys/icwmp/-/blob/devel/schemas/ubus/tr069.json)
### tr069 ubus examples
Please note, the output shown in below examples are just for demonstration purpose, the actual output shall vary as per the cwmp configuration and state.