blob: 41f8250cca6232d8dae631116c2cf622134bcdec [file] [log] [blame]
Andy Bavierf3e24b62022-03-30 19:53:01 -04001.. vim: syntax=rst
2
3Aether-in-a-Box on Hardware Radios (4G)
4=======================================
5
6This document describes how to set up an Aether-in-a-Box (AiaB) with
7a Sercomm eNodeB and connect real devices (e.g., 4G phones). This
8setup is suitable for laboratory experiments and proof-of-concept deployments.
9To create this setup you will need the following equipment:
10
11* Server for running AiaB (SD-CORE / UPF / ROC)
12
13 * Haswell CPU family or newer
14 * At least 4 CPUs and 12GB RAM
15 * Internet connection
16
17* Sercomm CBRS LTE small cell eNodeB
18
19 * 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>`_.
20
21* SIM card writer and blank SIM cards
22
23We assume that the server and the eNodeB are connected to the same
24LAN, and the LAN also provides external Internet connectivity.
25
26Preparation
27-----------
28
29Create SIM cards by following the instructions for your SIM card writer.
30Of course you are free to use any values for IMSI, etc. that you choose,
31but these are the values that will work with the rest of the configuration
32in this document:
33
34* IMSI: each one is unique, matching pattern ``315010*********`` (15 digits)
35* OPc: ``69d5c2eb2e2e624750541d3bbc692ba5``
36* Transport Key: ``000102030405060708090a0b0c0d0e0f``
37
38If you choose different values for your SIM cards, you will need to
39modify subsequent configuration steps appropriately.
40
41Insert the SIM cards in devices that you wish to be able to connect to the Aether network.
42
43Server setup
44------------
45
46The server will run Aether-in-a-Box. The eNodeB will connect to the server over the local network.
47Perform these steps to prepare the server for the AiaB install:
48
49* Connect the server to the local network
50* Perform a clean install of Ubuntu 18.04 on the server
51* Set up password-less sudo for the user that will install Aether-in-a-Box
52
53After the steps above have been completed, install Aether-in-a-Box as follows::
54
55 sudo apt install git make
56 git clone "https://gerrit.opencord.org/aether-in-a-box"
57 cd aether-in-a-box
58
59Next, modify the file *sd-core-4g-values.yaml*. Under ``subscribers``,
60add an IMSI range for the SIM cards you created, with the Transport Key
61and OPc values you used earlier. For example, the following will add
62IMSIs between 315010999912301 and 315010999912303::
63
64 subscribers:
65 - ueId-start: 315010999912301
66 ueId-end: 315010999912303
67 plmnId: 315010
68 opc: 69d5c2eb2e2e624750541d3bbc692ba5
69 key: 000102030405060708090a0b0c0d0e0f
70 sequenceNumber: 135
71
72Determine which is the interface that has L3 connectivity to the
Andy Bavier5a32da02022-04-01 13:46:54 -040073eNodeB -- this will be ``DATA_IFACE`` in the configuration later. If
Andy Bavierf3e24b62022-03-30 19:53:01 -040074the eNodeB will also be connected to the local network, then this is just the
75servers primary interface. If the eNodeB will be connected via an
Andy Bavier5a32da02022-04-01 13:46:54 -040076isolated L2/L3 network segment, then ``DATA_IFACE`` refers to the server
Andy Bavierf3e24b62022-03-30 19:53:01 -040077interface on that network. Remember this interface for later.
78
79Option 1: Configure Aether with ROC
80^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
81
82The Aether ROC provides a GUI and API for dynamically configuring
83Aether. If you dont wish to use the ROC to configure AiaB, you
84can skip to the next section.
85
Andy Bavier5a32da02022-04-01 13:46:54 -040086Install AiaB as follows (specifying ``DATA_IFACE`` from above)::
Andy Bavierf3e24b62022-03-30 19:53:01 -040087
88 ENABLE_OAISIM=false DATA_IFACE=<iface> CHARTS=latest make roc-4g-models 4g-core
89
90Next, use the ROC to add information about your SIM cards.
91The ROC GUI is available at `http://<server-ip>:31194`.
92
Andy Bavier5a32da02022-04-01 13:46:54 -040093Choose ``Configuration > Site`` from the drop-down at top right and edit
94the ``AiaB site``. Change the following values and click ``Update``:
Andy Bavierf3e24b62022-03-30 19:53:01 -040095
96* MCC: 315
97* MNC: 010
98
Andy Bavier5a32da02022-04-01 13:46:54 -040099Choose ``Sim Cards`` from the drop-down at top right. Edit the
Andy Bavierf3e24b62022-03-30 19:53:01 -0400100existing entries to reflect the SIM cards you are adding to devices
Andy Bavier5a32da02022-04-01 13:46:54 -0400101by replacing their IMSI values. Click ``Update`` after each edit.
Andy Bavierf3e24b62022-03-30 19:53:01 -0400102If you want to connect more than two devices, consult the `ROC
103documentation <https://docs.aetherproject.org/master/operations/subscriber.html#configure-connectivity-service-for-a-new-device>`_.
104
Andy Bavier5a32da02022-04-01 13:46:54 -0400105Finally, click the Basket icon at top right and click the ``Commit`` button.
Andy Bavierf3e24b62022-03-30 19:53:01 -0400106
107Now jump to the `Verifying the AiaB installation`_ section.
108
109Option 2: Configure Aether without ROC
110^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
111
112It is possible to configure Aether without the ROC,
113using static YAML files and the SimApp service. If you have already
114installed the ROC, you should skip this section.
115
116Edit *sd-core-4g-values.yaml*. Change ``mcc`` and ``mnc`` as follows::
117
118 plmn:
119 mcc: "315"
120 mnc: "010"
121
122Also add the IMSIs of your devices under ``imsis``, for example::
123
124 device-groups:
125 - name: "4g-oaisim-user"
126 imsis:
127 - "315010999912301"
128 - "315010999912302"
129 - "315010999912303"
130
Andy Bavier5a32da02022-04-01 13:46:54 -0400131Install AiaB as follows (specifying ``DATA_IFACE`` from above)::
Andy Bavierf3e24b62022-03-30 19:53:01 -0400132
133 ENABLE_OAISIM=false DATA_IFACE=<iface> CHARTS=latest make 4g-core
134
135Verifying the AiaB installation
136^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
137
138Installing AiaB will take about 20 minutes with a fast Internet
Andy Bavier5a32da02022-04-01 13:46:54 -0400139connection. If you see any errors / timeouts, try running the ``make``
Andy Bavierf3e24b62022-03-30 19:53:01 -0400140command again. The build will finish with a message:
141Your MME IP address is This is just the IP address assigned to
Andy Bavier5a32da02022-04-01 13:46:54 -0400142the ``DATA_IFACE``. Remember this for the eNodeB setup.
Andy Bavierf3e24b62022-03-30 19:53:01 -0400143
144When the install is complete, check that the 4G SD-CORE is running
145as follows::
146
147 $ kubectl -n omec get pod
148 NAME READY STATUS RESTARTS AGE
149 cassandra-0 1/1 Running 0 7m27s
150 config4g-0 1/1 Running 0 7m27s
151 hss-0 1/1 Running 0 7m27s
152 mme-0 4/4 Running 0 7m27s
153 pcrf-0 1/1 Running 0 7m27s
154 simapp-65dc44b9d-stx6q 1/1 Running 0 7m27s
155 spgwc-0 2/2 Running 0 7m27s
156 upf-0 5/5 Running 0 7m27s
157
158You should see all pods in Running status.
159
160If you have installed the ROC, check that all its pods are running
161as follows::
162
163 $ kubectl -n aether-roc get pod
164 NAME READY STATUS RESTARTS AGE
165 aether-roc-api-78cc548bb9-7vjs2 1/1 Running 0 4m16s
166 aether-roc-gui-v2-6d674fd446-tttb5 1/1 Running 0 4m16s
167 aether-roc-umbrella-grafana-74f8489c8f-s9p45 2/2 Running 0 4m16s
168 aether-roc-websocket-855d64549b-44fnc 1/1 Running 0 4m16s
169 onos-cli-5d448ff6c4-stq5t 1/1 Running 0 4m16s
170 onos-config-7f4df96b88-vtp5s 6/6 Running 0 4m16s
171 onos-consensus-store-0 1/1 Running 0 4m15s
172 onos-topo-585c7c8976-6jq7b 3/3 Running 0 4m16s
173 sdcore-adapter-v2-5646d455b9-2d6zl 1/1 Running 0 4m15s
174
175You should see all pods in Running status.
176
177Sercomm eNodeB setup
178--------------------
179
180The instructions in this section describe a basic configuration of
181the eNodeB. For a more comprehensive guide to
182eNodeB configuration see `eNB Installation <https://docs.aetherproject.org/master/edge_deployment/enb_installation.html>`_.
183
184The Sercomm eNodeB has two Ethernet ports: WAN and LAN. We will use
185the LAN port for configuration of the eNodeB and the WAN port for
186normal operation. Connect the eNodeB WAN port to the local network.
187
188Connect the eNodeB LAN port to a free Ethernet port on a Linux machine
189(say, a laptop) that will be used for the initial configuration of
Andy Bavier5a32da02022-04-01 13:46:54 -0400190the eNodeB. On that machine run ``dhclient`` on the interface corresponding
Andy Bavierf3e24b62022-03-30 19:53:01 -0400191to the Ethernet port, for example::
192
193 sudo dhclient eth1
194
195The interface should receive an IP address from the Sercomm eNodeB on
Andy Bavier5a32da02022-04-01 13:46:54 -0400196the 11.11.11.0/24 subnet. Check this using ``ifconfig``::
Andy Bavierf3e24b62022-03-30 19:53:01 -0400197
198 $ ifconfig eth1
199 eth1: flags=4163<UP,BROADCAST,RUNNING,MULTICAST> mtu 1500
200 inet 11.11.11.100 netmask 255.255.255.0 broadcast 11.11.11.255
201 inet6 fe80::2e0:4cff:fe68:2f76 prefixlen 64 scopeid 0x20<link>
202 ether 00:e0:4c:68:2f:76 txqueuelen 1000 (Ethernet)
203 RX packets 264652 bytes 216094312 (216.0 MB)
204 RX errors 0 dropped 0 overruns 0 frame 0
205 TX packets 183978 bytes 36528580 (36.5 MB)
206 TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0
207
208The eNodeB IP address should be 11.11.11.188 on that link. Verify
209this using ping::
210
211 $ ping 11.11.11.188
212
213To access the Sercomm eNodeB admin page, you can run a Web browser on
214the laptop and direct it to `https://11.11.11.188`. Login to the admin
Andy Bavier5a32da02022-04-01 13:46:54 -0400215interface as user: ``sc_femto`` and password: ``scHt3pp``.
Andy Bavierf3e24b62022-03-30 19:53:01 -0400216
217Click the ``NetWork set`` menu at the top. In the first section
Andy Bavier5a32da02022-04-01 13:46:54 -0400218``IP Address``, set *Connect type: DHCP* (assuming this is supported on
Andy Bavierf3e24b62022-03-30 19:53:01 -0400219your local network, otherwise set up a static IP address).
220Click the blue ``Save`` button at the bottom.
221
222Next, click the ``Manage`` menu at the top and then click the
223``LTE Basic Setting`` tab. Change these parameters and click ``Save``:
224
225* Carrier Number: 2
226* Carrier Aggregation: Unset
227* BandWidth: 20
228* FrequencyBand: 48,48
229* EARFCN: 55440,55640
230* CellIdentity: 2,1
231* PCI: 100,101
232* TxPower: 20
233* Tunnel Type: IPv4
234* MME IP Address: <MME IP address from AiaB installation>
235* PLMNID: 315010
236* TAC: 1
237* Sync Source: FREE_RUNNING
238* Enable CWMP: Unset
239
240Click the ``SAS Configuration`` tab. In the ``Location Configuration``
241section, enter these values and click Save”:
242
243* Location: Indoor
244* Location Source: Manual
245* Latitude: 0
246* Longitude: 0
247* Elevation: -18000
248
249Next we need to add a static route to the UPF address, 192.168.252.3,
250on the eNodeB. Click on ``TR098`` menu and then click on ``IP`` tab.
251Scroll down to ``Device.Routing.Router.`` section. Click ``View List``.
252Add this info on the blank line:
253
254* Enable: Set
255* StaticRoute: Set
256* DestIPAddress: 192.168.252.0
257* DestSubnetMask: 255.255.255.0
258* GatewayIPAddress: <Use MME IP address from AiaB installation>
259* Interface: Device.IP.Interface.1.
260
Andy Bavier5a32da02022-04-01 13:46:54 -0400261Then click the ``Add`` button at the far right.
Andy Bavierf3e24b62022-03-30 19:53:01 -0400262
263Finally click the ``FAPService`` menu and then go to the ``FAPControl``
264tab. Check the box next to ``AdminState`` in the first section and
265click ``Save``.
266
267After these changes are made, reboot the eNodeB by clicking the red
268``power button`` square at top right and selecting ``Reboot``. When the
269eNodeB comes back up, it should have an IP address on the network
270(via the WAN port), and the admin page should now be available on
271`https://<endoeb-ip>`.
272
273Test connectivity from the eNodeB to the MME and the UPF running on
274the server as follows. Login to the eNodeB admin interface, click
275the Manage menu at the top, and click the ``IP Diagnose`` tab. Under
276``Ping and Traceroute``, select ``ping``, and then type the following IP
277addresses into the box to the right and click ``Run``:
278
279* <MME IP address from AiaB installation>
280* 192.168.251.1
281* 192.168.252.3
282
283If all of these are working, then you are ready to try to connect
284devices to the network.
285
286Connecting Devices
287------------------
288
Andy Bavier6f431e42022-04-01 13:52:22 -0400289Documenting how to configure different types of devices to work
290with Aether is work-in-progress.
Andy Bavierf3e24b62022-03-30 19:53:01 -0400291
292Reinstalling AiaB
293-----------------
294
295A current limitation of AiaB is that if the host machine reboots,
296AiaB needs to be reinstalled. We plan to fix this in the future so
297that the AiaB configuration will persist across reboots. In the
298meantime, to reinstall AiaB on a machine where it was previously
299installed, run `make clean` and then start at the `Server setup`_
300section above.