AETHER-3345 Add AiaB on Real Radios
Change-Id: I24308be78fd0d047daf75d7bdf07fa9dbf287424
diff --git a/developer/aiab.rst b/developer/aiab.rst
index 096ffb8..8d503f2 100644
--- a/developer/aiab.rst
+++ b/developer/aiab.rst
@@ -1,7 +1,7 @@
.. vim: syntax=rst
-Setting Up Aether-in-a-Box
-==========================
+Aether-in-a-Box for Developers
+==============================
Aether-in-a-Box (AiaB) provides an easy way to deploy Aether's SD-CORE and ROC
components, and then run basic tests to validate the installation.
diff --git a/developer/aiabhw.rst b/developer/aiabhw.rst
new file mode 100644
index 0000000..e405c4a
--- /dev/null
+++ b/developer/aiabhw.rst
@@ -0,0 +1,300 @@
+.. vim: syntax=rst
+
+Aether-in-a-Box on Hardware Radios (4G)
+=======================================
+
+This document describes how to set up an Aether-in-a-Box (AiaB) with
+a Sercomm eNodeB and connect real devices (e.g., 4G phones). This
+setup is suitable for laboratory experiments and proof-of-concept deployments.
+To create this setup you will need the following equipment:
+
+* Server for running AiaB (SD-CORE / UPF / ROC)
+
+ * Haswell CPU family or newer
+ * At least 4 CPUs and 12GB RAM
+ * Internet connection
+
+* Sercomm CBRS LTE small cell eNodeB
+
+ * Firmware version 3918 or newer. For instructions on how to update the firmware see `here <https://docs.aetherproject.org/master/edge_deployment/enb_installation.html#upgrade-firmware>`_.
+
+* SIM card writer and blank SIM cards
+
+We assume that the server and the eNodeB are connected to the same
+LAN, and the LAN also provides external Internet connectivity.
+
+Preparation
+-----------
+
+Create SIM cards by following the instructions for your SIM card writer.
+Of course you are free to use any values for IMSI, etc. that you choose,
+but these are the values that will work with the rest of the configuration
+in this document:
+
+* IMSI: each one is unique, matching pattern ``315010*********`` (15 digits)
+* OPc: ``69d5c2eb2e2e624750541d3bbc692ba5``
+* Transport Key: ``000102030405060708090a0b0c0d0e0f``
+
+If you choose different values for your SIM cards, you will need to
+modify subsequent configuration steps appropriately.
+
+Insert the SIM cards in devices that you wish to be able to connect to the Aether network.
+
+Server setup
+------------
+
+The server will run Aether-in-a-Box. The eNodeB will connect to the server over the local network.
+Perform these steps to prepare the server for the AiaB install:
+
+* Connect the server to the local network
+* Perform a clean install of Ubuntu 18.04 on the server
+* Set up password-less sudo for the user that will install Aether-in-a-Box
+
+After the steps above have been completed, install Aether-in-a-Box as follows::
+
+ sudo apt install git make
+ git clone "https://gerrit.opencord.org/aether-in-a-box"
+ cd aether-in-a-box
+
+Next, modify the file *sd-core-4g-values.yaml*. Under ``subscribers``,
+add an IMSI range for the SIM cards you created, with the Transport Key
+and OPc values you used earlier. For example, the following will add
+IMSIs between 315010999912301 and 315010999912303::
+
+ subscribers:
+ - ueId-start: 315010999912301
+ ueId-end: 315010999912303
+ plmnId: 315010
+ opc: 69d5c2eb2e2e624750541d3bbc692ba5
+ key: 000102030405060708090a0b0c0d0e0f
+ sequenceNumber: 135
+
+Determine which is the interface that has L3 connectivity to the
+eNodeB -- this will be *DATA_IFACE* in the configuration later. If
+the eNodeB will also be connected to the local network, then this is just the
+server’s primary interface. If the eNodeB will be connected via an
+isolated L2/L3 network segment, then *DATA_IFACE* refers to the server
+interface on that network. Remember this interface for later.
+
+Option 1: Configure Aether with ROC
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The Aether ROC provides a GUI and API for dynamically configuring
+Aether. If you don’t wish to use the ROC to configure AiaB, you
+can skip to the next section.
+
+Install AiaB as follows (specifying *DATA_IFACE* from above)::
+
+ ENABLE_OAISIM=false DATA_IFACE=<iface> CHARTS=latest make roc-4g-models 4g-core
+
+Next, use the ROC to add information about your SIM cards.
+The ROC GUI is available at `http://<server-ip>:31194`.
+
+Choose *Configuration > Site* from the drop-down at top right and edit
+the “AiaB site”. Change the following values and click “Update”:
+
+* MCC: 315
+* MNC: 010
+
+Choose *Sim Cards* from the drop-down at top right. Edit the
+existing entries to reflect the SIM cards you are adding to devices
+by replacing their IMSI values. Click “Update” after each edit.
+If you want to connect more than two devices, consult the `ROC
+documentation <https://docs.aetherproject.org/master/operations/subscriber.html#configure-connectivity-service-for-a-new-device>`_.
+
+Finally, click the Basket icon at top right and click the “Commit” button.
+
+Now jump to the `Verifying the AiaB installation`_ section.
+
+Option 2: Configure Aether without ROC
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It is possible to configure Aether without the ROC,
+using static YAML files and the SimApp service. If you have already
+installed the ROC, you should skip this section.
+
+Edit *sd-core-4g-values.yaml*. Change ``mcc`` and ``mnc`` as follows::
+
+ plmn:
+ mcc: "315"
+ mnc: "010"
+
+Also add the IMSIs of your devices under ``imsis``, for example::
+
+ device-groups:
+ - name: "4g-oaisim-user"
+ imsis:
+ - "315010999912301"
+ - "315010999912302"
+ - "315010999912303"
+
+Install AiaB as follows (specifying *DATA_IFACE* from above)::
+
+ ENABLE_OAISIM=false DATA_IFACE=<iface> CHARTS=latest make 4g-core
+
+Verifying the AiaB installation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Installing AiaB will take about 20 minutes with a fast Internet
+connection. If you see any errors / timeouts, try running the `make`
+command again. The build will finish with a message:
+“Your MME IP address is… ” This is just the IP address assigned to
+the *DATA_IFACE*. Remember this for the eNodeB setup.
+
+When the install is complete, check that the 4G SD-CORE is running
+as follows::
+
+ $ kubectl -n omec get pod
+ NAME READY STATUS RESTARTS AGE
+ cassandra-0 1/1 Running 0 7m27s
+ config4g-0 1/1 Running 0 7m27s
+ hss-0 1/1 Running 0 7m27s
+ mme-0 4/4 Running 0 7m27s
+ pcrf-0 1/1 Running 0 7m27s
+ simapp-65dc44b9d-stx6q 1/1 Running 0 7m27s
+ spgwc-0 2/2 Running 0 7m27s
+ upf-0 5/5 Running 0 7m27s
+
+You should see all pods in Running status.
+
+If you have installed the ROC, check that all its pods are running
+as follows::
+
+ $ kubectl -n aether-roc get pod
+ NAME READY STATUS RESTARTS AGE
+ aether-roc-api-78cc548bb9-7vjs2 1/1 Running 0 4m16s
+ aether-roc-gui-v2-6d674fd446-tttb5 1/1 Running 0 4m16s
+ aether-roc-umbrella-grafana-74f8489c8f-s9p45 2/2 Running 0 4m16s
+ aether-roc-websocket-855d64549b-44fnc 1/1 Running 0 4m16s
+ onos-cli-5d448ff6c4-stq5t 1/1 Running 0 4m16s
+ onos-config-7f4df96b88-vtp5s 6/6 Running 0 4m16s
+ onos-consensus-store-0 1/1 Running 0 4m15s
+ onos-topo-585c7c8976-6jq7b 3/3 Running 0 4m16s
+ sdcore-adapter-v2-5646d455b9-2d6zl 1/1 Running 0 4m15s
+
+You should see all pods in Running status.
+
+Sercomm eNodeB setup
+--------------------
+
+The instructions in this section describe a basic configuration of
+the eNodeB. For a more comprehensive guide to
+eNodeB configuration see `eNB Installation <https://docs.aetherproject.org/master/edge_deployment/enb_installation.html>`_.
+
+The Sercomm eNodeB has two Ethernet ports: WAN and LAN. We will use
+the LAN port for configuration of the eNodeB and the WAN port for
+normal operation. Connect the eNodeB WAN port to the local network.
+
+Connect the eNodeB LAN port to a free Ethernet port on a Linux machine
+(say, a laptop) that will be used for the initial configuration of
+the eNodeB. On that machine run `dhclient` on the interface corresponding
+to the Ethernet port, for example::
+
+ sudo dhclient eth1
+
+The interface should receive an IP address from the Sercomm eNodeB on
+the 11.11.11.0/24 subnet. Check this using `ifconfig`::
+
+ $ ifconfig eth1
+ eth1: flags=4163<UP,BROADCAST,RUNNING,MULTICAST> mtu 1500
+ inet 11.11.11.100 netmask 255.255.255.0 broadcast 11.11.11.255
+ inet6 fe80::2e0:4cff:fe68:2f76 prefixlen 64 scopeid 0x20<link>
+ ether 00:e0:4c:68:2f:76 txqueuelen 1000 (Ethernet)
+ RX packets 264652 bytes 216094312 (216.0 MB)
+ RX errors 0 dropped 0 overruns 0 frame 0
+ TX packets 183978 bytes 36528580 (36.5 MB)
+ TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0
+
+The eNodeB IP address should be 11.11.11.188 on that link. Verify
+this using ping::
+
+ $ ping 11.11.11.188
+
+To access the Sercomm eNodeB admin page, you can run a Web browser on
+the laptop and direct it to `https://11.11.11.188`. Login to the admin
+interface as user: *sc_femto* and password: *scHt3pp*.
+
+Click the ``NetWork set`` menu at the top. In the first section
+“IP Address”, set *Connect type: DHCP* (assuming this is supported on
+your local network, otherwise set up a static IP address).
+Click the blue ``Save`` button at the bottom.
+
+Next, click the ``Manage`` menu at the top and then click the
+``LTE Basic Setting`` tab. Change these parameters and click ``Save``:
+
+* Carrier Number: 2
+* Carrier Aggregation: Unset
+* BandWidth: 20
+* FrequencyBand: 48,48
+* EARFCN: 55440,55640
+* CellIdentity: 2,1
+* PCI: 100,101
+* TxPower: 20
+* Tunnel Type: IPv4
+* MME IP Address: <MME IP address from AiaB installation>
+* PLMNID: 315010
+* TAC: 1
+* Sync Source: FREE_RUNNING
+* Enable CWMP: Unset
+
+Click the ``SAS Configuration`` tab. In the ``Location Configuration``
+section, enter these values and click “Save”:
+
+* Location: Indoor
+* Location Source: Manual
+* Latitude: 0
+* Longitude: 0
+* Elevation: -18000
+
+Next we need to add a static route to the UPF address, 192.168.252.3,
+on the eNodeB. Click on ``TR098`` menu and then click on ``IP`` tab.
+Scroll down to ``Device.Routing.Router.`` section. Click ``View List``.
+Add this info on the blank line:
+
+* Enable: Set
+* StaticRoute: Set
+* DestIPAddress: 192.168.252.0
+* DestSubnetMask: 255.255.255.0
+* GatewayIPAddress: <Use MME IP address from AiaB installation>
+* Interface: Device.IP.Interface.1.
+
+Then click the “Add” button at the far right.
+
+Finally click the ``FAPService`` menu and then go to the ``FAPControl``
+tab. Check the box next to ``AdminState`` in the first section and
+click ``Save``.
+
+After these changes are made, reboot the eNodeB by clicking the red
+``power button`` square at top right and selecting ``Reboot``. When the
+eNodeB comes back up, it should have an IP address on the network
+(via the WAN port), and the admin page should now be available on
+`https://<endoeb-ip>`.
+
+Test connectivity from the eNodeB to the MME and the UPF running on
+the server as follows. Login to the eNodeB admin interface, click
+the “Manage” menu at the top, and click the ``IP Diagnose`` tab. Under
+``Ping and Traceroute``, select ``ping``, and then type the following IP
+addresses into the box to the right and click ``Run``:
+
+* <MME IP address from AiaB installation>
+* 192.168.251.1
+* 192.168.252.3
+
+If all of these are working, then you are ready to try to connect
+devices to the network.
+
+Connecting Devices
+------------------
+
+Is there already a document on how to configure different devices
+to work with an Aether SIM card?
+
+Reinstalling AiaB
+-----------------
+
+A current limitation of AiaB is that if the host machine reboots,
+AiaB needs to be reinstalled. We plan to fix this in the future so
+that the AiaB configuration will persist across reboots. In the
+meantime, to reinstall AiaB on a machine where it was previously
+installed, run `make clean` and then start at the `Server setup`_
+section above.
diff --git a/dict.txt b/dict.txt
index 66406c5..187b4eb 100644
--- a/dict.txt
+++ b/dict.txt
@@ -41,7 +41,9 @@
ONF
ONL
ONOS
+OPc
PFCP
+PoC
PoE
QoS
ROC
diff --git a/index.rst b/index.rst
index a5aedcb..6bd9ecd 100644
--- a/index.rst
+++ b/index.rst
@@ -11,15 +11,16 @@
Here are some useful places to start with Aether:
-* Read the most recent :doc:`Release Notes </release/1.5>`.
+* Setup an Aether software development environment with :doc:`Aether-in-a-Box </developer/aiab>`.
+
+* For a PoC deployment, bring up an :doc:`Aether-in-a-Box on Real Radios <developer/aiabhw>`.
+
+* Learn about how to :doc:`configure Aether using the ROC </operations/gui>`.
* Learn the requirements of hosting an :doc:`Aether Connected Edge
</edge_deployment/overview>`.
-* Learn about the :doc:`Aether Managemnt Platform </amp/roc>`.
-
-* Setup an Aether software development environment with :doc:`Aether-in-a-Box
- </developer/aiab>`.
+* Read the most recent :doc:`Release Notes </release/2.0>`.
Aether Architecture and Components
----------------------------------
@@ -54,7 +55,30 @@
.. toctree::
:maxdepth: 3
- :caption: Edge Deployment
+ :caption: Aether Quick Start
+ :hidden:
+ :glob:
+
+ developer/aiab
+ developer/aiabhw
+
+.. toctree::
+ :maxdepth: 3
+ :caption: Operations
+ :hidden:
+ :glob:
+
+ operations/gui
+ operations/subscriber
+ operations/application
+ operations/slice
+ operations/metering
+ operations/monitor
+ operations/procedures
+
+.. toctree::
+ :maxdepth: 3
+ :caption: Production Edge Deployment
:hidden:
:glob:
@@ -85,17 +109,12 @@
.. toctree::
:maxdepth: 3
- :caption: Operations
+ :caption: ROC Development
:hidden:
:glob:
- operations/gui
- operations/subscriber
- operations/application
- operations/slice
- operations/metering
- operations/monitor
- operations/procedures
+ developer/roc
+ developer/roc-api
.. toctree::
:maxdepth: 3
@@ -109,16 +128,6 @@
testing/acceptance_specification
.. toctree::
- :maxdepth: 3
- :caption: Aether Developer Notes
- :hidden:
- :glob:
-
- developer/aiab
- developer/roc
- developer/roc-api
-
-.. toctree::
:maxdepth: 2
:caption: Releases
:hidden: