docs/developer-guide.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. SPDX-License-Identifier: CC-BY-4.0
   3 .. Copyright (C) 2020 CommScope Inc.
   4
   5 TR-069 Adapter Developer Guide
   6 ==============================
   7
   8 This document provides a quick start for developers of the O-RAN SC TR-069 Adapter
   9
  10 Prerequisites
  11 -------------
  12
  13 1. Java development kit (JDK), version 8 or later
  14 2. Maven dependency-management tool, version 3.4 or later
  15
  16
  17 Clone and Update
  18 ----------------
  19
  20 After cloning the repository, update the repository to latest fetch head
  21
  22
  23 Build Application
  24 -----------------
  25 TR-069 Adapter has 8 docker applications.
  26
  27 ++
  28 db
  29 ++
  30
  31 The Maria DB container instance is used to support data persistence for the TR-069Adapter covering initial PnP Configuration Data, TR-069 Session Data and Device Connection Request URL information.
  32
  33 +++
  34 acs
  35 +++
  36
  37 The Auto Configuration Service (ACS) Module is used to communicate with the Device using the TR-069 protocol. it contains the core tr069 layer split into 3 modules
  38         cpe: This module is responsible for sending http request/response to device.
  39         nbi: This module is responsible for interacting with mapper module
  40         requestprocessor: this module is responsible for processing the informs/nbi request from mapper and handing over to respective cpe/nbi modules
  41
  42 +++++++
  43 factory
  44 +++++++
  45
  46 This module supports Rest APIs to authenticate Device TR-069 sessions using basic authentication.
  47 As of now it's dummy implementation, user can extend the code of FactoryDataController.java to support as per user requirements. For Example: If user wants to authenticate with DB, the extended class can implement DAO layer and verify in the database.
  48
  49 +++++++++++
  50 config-data
  51 +++++++++++
  52
  53 This module supports importing 3GPP Configuration XML (3GPP TS 32.594) for Device. The configurations from XML are used to provision as initial PnP parameters to devices as part of BootStrap. This module also supports REST APIs to import Config XML which contains device Initial PnP Configurations. The initial PnP Parameters are optional and could be used to emulate PnP using TR-069Adapter.
  54
  55 ++++++
  56 mapper
  57 ++++++
  58
  59 The main function of this module is to map the request between NETCONF server and ACS (conversion of NETCONF protocol specific message to TR-069 message and vice versa) and to forward notifications to the VES Notifier.
  60
  61 Mapper module will have a mapping file in CSV format which contains a mapping between TR069 MO name and its equivalent Yang MO name, MO type and equivalent TR069 data type.
  62
  63 $tr069-adapter/mapper/mapper-schema# tree
  64
  65 | base
  66 |  ├── CSDMYangMONameMapping.txt
  67 |  └── CustomYangModelMOmapping.txt
  68
  69 The mapping file holds TRMONAME,YANGMONAME,MOTYPE,TRDATATYPE. Sample content is as shown below:
  70
  71 TRMONAME,YANGMONAME,MOTYPE,TRDATATYPE
  72 Device.,device,ScalarObject,object,urn:onf:otcc:wireless:yang:radio-access-196
  73 Device.DeviceInfo.,device.device-info,ScalarObject,object
  74 Device.DeviceInfo.DeviceCategory,device.device-info.device-category,Scalar-ReadOnly,string
  75 Device.DeviceInfo.Manufacturer,device.device-info.manufacturer,Scalar-ReadOnly,string
  76 Device.DeviceInfo.ManufacturerOUI,device.device-info.manufacturer-oui,Scalar-ReadOnly,string
  77 Device.Services.FAPService.{i}.,device.services.fap-service.{i}.,TabularObject,object,urn:onf:otcc:wireless:yang:radio-access
  78 Device.Services.FAPService.{i}.Alias,device.services.fap-service.{i}.alias,Tabular-ReadWrite,string
  79 Device.Services.FAPService.{i}.DeviceType,device.services.fap-service.{i}.device-type,Tabular-ReadOnly,string
  80
  81 Note: To retrieve different namespace, provide namespace value as an additional argument in corresponding node in the mapping file.
  82
  83 The mapping file location will have to be specified in 'profile-definition-mapping.json' as "csdm-mapping-dir-path" based on the software version. During the mapper startup it will load the mapping files defined 'profile-definition-mapping.json'.
  84
  85 profile-definition-mapping.json
  86 .. jsonschema::
  87
  88     {
  89         "profileDefinition":[{
  90                         "profile-id":"base",
  91                         "software-version":"*",
  92                         "hardware-version":"*",
  93                         "netconf-schema-dir-path":"base",
  94                         "csdm-mapping-dir-path":"base"
  95                 }]
  96     }
  97
  98 Mapper module exposes REST-API on the NBI to receive netconf rpc requests
  99 Mapper module also exposes REST-API on the SBI to receive acs notifications
 100
 101 ++++++++++++++
 102 netconf-server
 103 ++++++++++++++
 104
 105 A NETCONF compliant server is used to communicate to SDN-R’s NetConf Client. It internally uses the Yang Model built based on TR-196 and TR-181.
 106
 107 This module will create the netconf instances when it receives BOOTSTRAP from mapper module. While starting the the netconf instance, it will load the yang models from the path specified in "netconf-schema-dir-path" attribute in 'profile-definition-mapping.json' file based on software version. All common yang models will be placed "common" directory and version specific models under version based directory.
 108
 109 $ tr069-adapter/netconf-server/schemas# tree
 110
 111 |       ├── base
 112 |       │   ├── bbf-tr-196-2-0-3-full.yang
 113 |       │   ├── tr-069-cwmp-notification.yang
 114 |       │   └── tr-181-2-12-0-cwmp-full.yang
 115 |       └── common
 116 |               ├── iana-hardware.yang
 117 |               ├── ietf-crypto-types.yang
 118 |               ├── ietf-hardware.yang
 119 |               ├── ietf-inet-types.yang
 120 |               ├── ietf-netconf-acm.yang
 121 |               ├── ietf-netconf-monitoring-extension.yang
 122 |               ├── ietf-netconf-monitoring.yang
 123 |               ├── ietf-yang-types.yang
 124 |               ├── o-ran-file-management.yang
 125 |               ├── o-ran-hardware.yang
 126 |               ├── o-ran-heartbeat-management.yang
 127 |               ├── o-ran-software-management.yang
 128 |               └── tr069-operations.yang
 129
 130 +++++++++
 131 ves-agent
 132 +++++++++
 133 Any notification from the device sent through TR-069Adapter and Mapper, is forwarded to VES by this component. Whenever fault inform is reported by tr-69 device, acs module will forward this to ves-agent module, it will convert tr09 faults fields to VES fault fields and sent to VES-Collector via ngnix.
 134
 135 +++++
 136 nginx
 137 +++++
 138 This module is to offload the SSL communications between device and VES listener.
 139
 140 ++++++++++++
 141 How to build
 142 ++++++++++++
 143 To build, run below commands
 144
 145 $mvn clean install -Dmaven.test.skip=false
 146
 147 It will generate the docker images in the respective module target directories. To deploy the adapter refer deployment guide.