manual: Document ECBE; include JSON schema; cross-references

Change-Id: I358f72331aa9832cc56c67396eb41b62307a3258

doc/manuals/chapters/configuration.adoc

@@ -8,6 +8,7 @@ to communicate CSB and ETWS messages from the CBC to the BSC, who then
 subsequently distributes it among the (matching) cells within the BSC
 coverage area.
 
+[[config-cbsp]]
 ==== Configuring the CBSP connections
 
 According to 3GPP TS 48.049, a BSC typically operates as a TCP server,
@@ -63,6 +64,7 @@ cbc
   local-port 48049
 ----
 
+[[config-ecbe]]
 === ECBE (REST Interface) Configuration
 
 ==== Configuring the IP/Port for ECBE to bind to

doc/manuals/chapters/ecbe-rest-interface.adoc

@@ -0,0 +1,49 @@
+[[ecbe]]
+== ECBE REST interface
+
+The ECBE (External Cell Broadcast Entity) REST interface is specified in
+the JSON schema files `cbc.schema.json` and `smscb.schema.json`, which
+are part of the OsmoCBC distribution.
+
+The REST interface binds to the IP and TCP port as configured and
+can be reached at `http://IP:PORT/api/ecbe/v1`
+
+NOTE:: It is your responsibility to properly secure access to the REST
+interface endpoint to ensure only legitimate users can access it.  This
+may be achieved via packet filtering and a reverse HTTP proxy.
+
+=== API endpoints
+
+==== `POST /api/ecbe/v1/message`
+
+This command is used to create a new SMSCB or ETWS message inside the CBC.
+The `cbc_messsage` type as specified in the JSON schema (<<ecbe-json>>).
+
+==== `DELETE /api/ecbe/v1/message/:message_id`
+
+This command is used to delete an existing SMSCB or ETWS message from the CBC.
+
+The `:message_id` parameter is the decimal integer representation of the
+cbc_message.smscb.message_id that was specified when creating the
+message via the POST command stated above.
+
+[[ecbe-json]]
+=== JSON Schema
+
+==== `cbc.schema.json`
+
+This is the main JSOM schema for osmo-cbc.  In many places, it
+references `smscb.schema.json` described further below.
+
+----
+include::{srcdir}/../../cbc.schema.json[]
+----
+
+==== `smscb.schema.json`
+
+This JSON schema describes a lot of the basic data types relevant for
+SMSCB. It is used heavily by `cbc.schema.json` described above.
+
+----
+include::{srcdir}/../../smscb.schema.json[]
+----

doc/manuals/chapters/overview.adoc

@@ -49,29 +49,16 @@ that all BSCs need to know the IP address of the CBC.  In this situation,
 the CBC doesn't need to know each and every BSC in the network.  It
 simply only accepts incoming CBSP connections.
 
+For more information, see <<config-cbsp>> on how CBSP is configured.
 
-=== REST interface
+=== ECBE REST interface
 
-The REST interface is specified in the JSON schema files
-`cbc.schema.json` and `smscb.schema.json`, which are part of the OsmoCBC
-distribution.
+3GPP does not specify the external interface by which competent
+authorities can submit SMSCB and/or ETWS messages to a CBC.
 
-The REST interface currently binds to TCP port 12345 (on INADRR_ANY) and
-can be reached at http://localhost:1234/api/ecbe/v1"
+Hence, a non-standard, Osmocom specific  HTTP/REST/JSON based interface
+is offered for external entities to create and delete SMSCB and ETWS
+messages within the CBC.  This interface is called ECBE.
 
-NOTE:: It is your responsibility to properly secure access to the REST
-interface endpoint to ensure only legitimate users can access it.  This
-may be achieved via packet filtering and a reverse HTTP proxy.
-
-==== POST /api/ecbe/v1/message
-
-This command is used to create a new SMSCB or ETWS message inside the CBC.
-The `cbc_messsage` type as specified in the JSON schema.
-
-==== DELETE /api/ecbe/v1/message/:message_id
-
-This command is used to delete an existing SMSCB or ETWS message from the CBC.
-
-The `:message_id` parameter is the decimal integer representation of the
-cbc_message.smscb.message_id that was specified when creating the
-message via the POST command stated above.
+For more information, see <<ecbe>> on the ECBE API definition and <<config-ecbe>>
+on how it is configured.

doc/manuals/osmocbc-usermanual.adoc

@@ -16,6 +16,8 @@ include::{srcdir}/chapters/configuration.adoc[]
 
 include::{srcdir}/chapters/introspection.adoc[]
 
+include::{srcdir}/chapters/ecbe-rest-interface.adoc[]
+
 include::./common/chapters/counters-overview.adoc[]
 
 include::{srcdir}/chapters/counters.adoc[]