[VOL-4648] Generate basic response with ID and type for get request on devices
Change-Id: I5899ab9c2ae4449863d88439719c9cdf2036c1f7
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..c37a0c3
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,13 @@
+The goal of the voltha-northbound-bbf-adapter is to enable VOLTHA to be controlled through NETCONF using standard BBF yang modules. The current state of the translation between the two mainly consists in the use of the models from [TR-383](https://wiki.broadband-forum.org/display/BBF/TR-383%3A+Common+YANG+Modules+for+Access+Networks).\
+The architecture used by the adapter to achieve this involves the use of netopeer2 as a NETCONF server and sysrepo as its datastore. This configuration was proposed by BISDN, more information can be found in the [slides](https://wiki.broadband-forum.org/display/BBF/ONF+and+BBF+SEBA+Collaboration?preview=/131466119/141855024/20220309%20-%20vOLTHA%20adaption%20to%20BBF%20yang%20models.pptx).
+
+On its northbound, the BBF adapter interacts with sysrepo by acting as a plugin, using the APIs of libsysrepo.
+Instead, on its southbound, it interacts with VOLTHA's northbound APIs and the Olt ONOS app REST APIs to collect data and perform commands.
+
+
+
+# Additional documentation
+
+- [Deployment](deploy.md)
+- [Code structure](code_structure.md)
+- [Expanding functionality](expanding.md)
\ No newline at end of file
diff --git a/docs/code_structure.md b/docs/code_structure.md
new file mode 100644
index 0000000..4eb3e0d
--- /dev/null
+++ b/docs/code_structure.md
@@ -0,0 +1,46 @@
+# BBF Adapter code structure
+
+## `build` directory and Docker images
+
+The `build` directory contains the files used for the creation of a voltha-northbound-bbf-adapter Docker image that can be used for deployment.
+
+- `build/tools` contains the Dockerfile of the "builder" image. This image includes a golang toolchain and the .deb packages for libyang and sysrepo.\
+The presence of these packages allows the correct compilation of the project, which would otherwise fail due to missing dependencies. The same image is used for linting and testing through the Makefile.
+- `build/package` contains the Dockerfile of the actual BBF adapter image. It uses the builder image to compile the code of this repository. The generated binaries are then copied on the production image, where packages for libyang, sysrepo and netopeer2 are installed.\
+During this step, the yang files in `build/yang-files` are installed with sysrepoctl, making them available at runtime.\
+A user account that can be used to log in to netopeer2 is also created at this time. The credentials of this user can be changed by setting the `NETCONF_USER` and `NETCONF_PASSWORD` arguments.
+
+When the adapter image is deployed with the `onf/voltha-northbound-bbf-adapter` helm chart defined in [voltha-helm-charts](https://github.com/opencord/voltha-helm-charts), netopeer2 is automatically started with the `netopeer2-server` command before running the adapter itself.
+
+## `cmd` directory
+
+The `cmd/bbf-adapter` directory contains the source for the main function of the adapter.\
+`main.go` loads the configuration provided through CLI flags by the user, starts all the necessary components defined in the `internal` directory, keeps track of the adapter's readiness status and exposes it through the probe package of voltha-lib-go.
+
+## `internal` directory
+
+The `interal` directory contains the remaining logic of the adapter, split in multiple packages.
+
+### `internal/clients`
+
+This package contains the implementation of clients that the adapter can use to interact with the VOLTHA components that are necessary to provide its funcionality.
+- `nbi.go` provides a connection to VOLTHA's "northbound interface" gRPC service, which can be used to interact with the core the same way a user would using voltctl. This client can be used to list the devices, provision a new OLT and enable it.
+- `olt_app.go` provides wrapper functions for the REST APIs exposed by the Olt ONOS application. This client can be used to provision a subscriber on a specific device and port.
+
+### `internal/config`
+
+This package contains the definition of CLI flags that can be used to configure the adapter's behavior, and their default values.
+
+### `interal/core`
+
+This package contains the implementation of the VolthaYangAdapter (`adapter.go`), an instance of which is exposed globally as core.AdapterInstance. This is necessary because the callback functions defined in `internal/sysrepo/syrepo.go` would have no other way to reference it when being called from sysrepo.\
+VolthaYangAdapter provides methods to perform actions through its clients or request data from them. In the latter case, the functions defined in `translation.go` are used to translate information to a set of yang paths and values that will be used to update the NETCONF datastore.
+
+### `internal/sysrepo`
+
+Since sysrepo doesn't provide official bindings for golang, this project uses CGO to interact with sysrepo through its official C library: libsysrepo.
+
+- `plugin.c` is a C file used to include dependencies (like libyang and sysrepo header files) and define some utilities that make it possible to perform all the necessary operations through CGO.
+- `sysrepo.go` imports `plugin.c` and defines the SysrepoPlugin struct, which keeps track of the adapter's connection with sysrepo. At startup, a connection is created and the necessary callback functions are registered.
+
+When a NETCONF operation is executed on one of the modules managed by the BBF adapter, the corresponding go function will be called. The latter will interact with the global instance of VolthaYangAdapter to fulfill the request and provide a result, eventually updating the content of the datastore.
\ No newline at end of file
diff --git a/docs/deploy.md b/docs/deploy.md
index 44f5a3a..0f80c77 100644
--- a/docs/deploy.md
+++ b/docs/deploy.md
@@ -13,7 +13,7 @@
```
helm upgrade --install --create-namespace -n voltha bbf \
- onf/voltha-northbound-bbf-adapter/ --devel \
+ onf/voltha-northbound-bbf-adapter --devel \
--set global.voltha_infra_name=voltha-infra \
--set global.voltha_infra_namespace=infra \
--set global.voltha_stack_name=voltha \
@@ -54,11 +54,9 @@
After a successful login, a request can be performed:
```
-get-data --datastore operational --filter-xpath /bbf-device-aggregation:devices
+get-data --datastore operational --filter-xpath /bbf-device-aggregation:*
```
-The adapter doesn't perform request translations yet, but the success of the operation can be inferred by looking at the container's logs, which will show a `>>>>>>>RECEIVED REQUEST FROM SYSREPO<<<<<<<` message.
-
## Stop the BBF adapter
```
helm delete -n voltha bbf
diff --git a/docs/expanding.md b/docs/expanding.md
new file mode 100644
index 0000000..eb7b773
--- /dev/null
+++ b/docs/expanding.md
@@ -0,0 +1,14 @@
+# Expanding the adapter's functionality
+
+## Resources
+- [libsysrepo API documentation](https://netopeer.liberouter.org/doc/sysrepo/master/html/modules.html)
+- [libyang API documentation](https://netopeer.liberouter.org/doc/libyang/master/html/modules.html)
+
+## How to expand the adapter's functionality by creating new callbacks
+
+- If additional yang modules are needed, add them to `build/yang-files` to be installed to sysrepo during the creation of the adapter's Docker image
+- A new callback function has to be created. CGO cannot directly express the `const` keyword used in the signature of the C callbacks of libsysrepo.\
+For this reason, a Go function can be created and exposed in `internal/sysrepo/sysrepo.go`, while its corresponding wrapper with the right signature has to be created in `internal/sysrepo/plugin.go`.
+- The new callback wrapper has to be registered in the StartNewPlugin function of `internal/sysrepo/sysrepo.go`, using the sysrepo API to subscribe to the desired type of operation and XPath.
+- The Golang callback will interact with VOLTHA through the instance of VolthaYangAdapter exposed by the `core.AdapterInstance` variable.\
+If the operation needed by the new callback is not implemented already, it can be created as a new method in `internal/core/adapter.go`, eventually expanding the capabilities of the clients in `internal/clients/nbi.go` and `internal/clients/olt_app.go`, or creating new translation functions in `internal/core/translation.go`.
\ No newline at end of file