Requirements
Here are the requirements to check before following this procedure:
- Make sure to follow ORS Assembly Process - Configure your laptop
- You should have access to rapidspace.ors account on panel.rapid.space
- You should have the rights to create production orders and view sale packing lists on ERP5
This tutorial will teach you how to assemble, configure, test, record on ERP5 and package ORS products to Rapid.Space Clients.
You should read carefully each step, even though in some cases some steps will not apply to you if they have already been done previously by someone else.
Related Links
Terminology
- ORS: Open Radio Station
- SDR: Software Defined Radio
- PCB: Printed Circuit Board
- SDR Main Board / PCB / SDR PCB: These different terms all usually refer to the Radio Board inside the ORS designed by us : https://lab.nexedi.com/nexedi/ors-hardware
- SBC: Single Board Computer (may also be referred to as PC or Computer)
- ORS products (check out https://shop.rapid.space/simpleran for more details and pictures of each product):
- ORS Classic / ORS: 2x1 Watts, one SDR, one SBC
- ORS Duo: 4x1 Watts, two SDR + one SBC
- ORS Brute: 2x20 Watts, one SDR + one SBC in a special enclosure with high power amplifiers
- ORS 5-Pack: 1 B39 ORS + 5 5G Oukitel Smartphones
- 5G Sysmocom SIM Cards: SIM Cards with many 5G features
- UE: User Equipment, such as a smartphone or a modem
- ORS UE Mode: Special mode in which the ORS functions as a UE, allowing it to connect to another 4G / 5G Base station (such as an ORS)
Check sale packing list
While preparing an order for a client, you should always refer to the corresponding sale packing list.
If you have the required permissions you can click on this link to see the list of sale packing lists to ship: Sale Packing Lists to ship
Else, make sure the sale packing list document has been sent to you and use it as a reference.
Check each sale packing list line in detail to check what to ship, be careful to check the quantity also.
Carefully read all the sale packing list lines and refer to the Terminology section to understand what each line means. There may be lines not part of the standard set of Simpleran products for various products which we resell such as: Antennas, Special POE Injectors, RF Cables, RF Adaptors etc...
Assign which ORS number to use
If the ORS you assemble doesn't already have an assigned reference you may check this page to know which number to use: https://www.erp5.com/rapidspace-Produced.ORS.List . Be careful, on this page, there are different tables for ORS classic, ORS brute and ORS Duo.
Use the next available number and then check on panel.rapid.space that the compute node does not already exist. Edit the page to write the number you selected with basic information on the client and the band.
Use the prepare_ors Script
The prepare_ors script will do the following:
- Request Re6st token
- Register on Re6st and SlapOS using inputted slapOS token
- Create certificate tar file or modify an existing one
- Flash SSD
- Detect ORS on LAN Network
- Upgrade the ORS
- Check slapOS software has been installed on ORS, then request services
- Check services monitor base URL
- Request SIM Cards
- Check SIM Cards have been allocated
To run the script, first switch to root user using the sudo su - command. You should not use sudo as it will not have the right environment, using su - -c might also fail in some cases, for instance ssh-agent from root user might not be loaded on ubuntu when running from su.
If you exit the script at some point you can run it again and it should skip steps which are already done. For instance if it detects you have SSH access to the ORS you are preparing it will assume SSD is already flashed and installed, and ORS is already registered.
The script will guide you and automate certain things, but you should still follow all sections of this procedure along the script to know what to do at each step.
Case 1: preparing an ORS from scratch (assembly included):
If you are preparing an ORS from scratch, run the following command:
simpleran-tools/oss> ./prepare_ors.py
- You are preparing an ORS from scratch
Case 2: preparing an ORS already assembled
In that case, you likely will need to transfer the ORS to a different project it is currently assigned. There are two options to do this:
- Open the ORS, take out the SSD and reflash it: do this only if the ORS has been used previously and there is a risk some files outside of slapOS have been altered (such as program installed with apt, configuration files changed in /etc, things added in cron etc...)
- Use the prepare_ors script with --live option: this will allow you to move the ORS to a different project through SSH
simpleran-tools/oss> ./prepare_ors.py --live
Other cases:
For any other cases, please follow rapidspace-ORS-HowTo.Add.An.ORS.To.The.Panel
Get Slapos Token
The prepare_ors script will prompt you to enter a slapOS token, this token is necessary to add a Compute Node to a project. To get it do the following:
- Login as rapidspace.ors to panel.rapid.space
- Go to Projects
- Select the client's Project (be careful to select the correct project, in case of doubt double check with sales team)
- Click "Add computer token"
Destroy previous compute node if needed
If you are not preparing an ORS from scratch and you are using the --live option from the prepare_ors script, the script will ask you to destroy the previous Compute node and services (if you are preparing an ORS from scratch you can skip this section).
- Go to "Server" page
- Search for your ORS
- Click on it, then click on the project in "Current project"
- Destroy all the services from that ORS
- Go back to the compute node
- Click "Request Destroy"
- Confirm
Then you can press enter in the script and continue
Wait for Re6st token
After entering the slapOS token, the script will request the re6st token and you will have to wait 5 to 10 minutes until it is ready.
Add Compute Node to allocation supply
After the script has registered the Compute Node, you should get a message asking you to disable monitoring and add the node to the allocation supply.
Go to the project on the panel and check if the ORS is there.
Then, disable monitoring on the ORS computer to prevent useless ticket generation when ORS are powered off:
- Go to the client's project
- Go to the computer corresponding to the ORS
- Set "Monitor Scope" to "Disabled"
Finally, add the compute node to the "ORS Services" allocation supply, and invalidate and validate it.
Flash SSD
Then, unless you are using --live option you will be asked to plug the SSD to the laptop. If you don't have the SSD ready yet, you can leave the script paused and proceed to ORS assembly.
You don't have to leave the script running, by then the script has generated a tar file containing the slapOS and Re6st certificates (as well as few other things) and when you run the script again you will need to run it without entering any slapOS token and it will then detect the certificate tar file and use it to flash the SSD.
Assemble the ORS and make Production Order
Follow all these steps:
Additional procedures for products other than ORS:
Detect ORS on LAN
After flashing the SSD, the prepare_ors script should ask you to press Enter once the ORS is plugged to the LAN, and it will then automatically detect the ORS using a multicast IPv6 ping to detect machines on LAN and then using your ssh-agent to try to SSH to those IPs. Normally the script should have previously detected your SSH public key and added it the /root/.ssh/authorized_key file in SSD when flashing it, if this is not the case then ask someone from ORS team who has access to the ORS.
If you have exited the script by mistake and / or it did not detect the ORS, run the discover-ips script manually with -u option, then once the ORS has been added to your root SSH config the script will skip all the previous steps and proceed to the next steps if it detects it can SSH to the ORS.
Upgrade ORS Computer and PCB
The prepare_ors script will do the following upgrades:
- Run the ORS playbook
- If needed, flash EEPROM which contains the serial number, band and version of the PCB
- If needed, flash the FPGA of the PCB to the latest version
If you want to do the upgrade without the prepare_ors script, follow rapidspace-ORS.HowTo.Upgrade.ORS.After.Assembly
Request ORS Services
Next, the prepare_ors script will request all necessary services on the ORS, and it will check that each service obtains a working monitor base URL (which is the URL served by the Rapid.Space CDN used for monitoring the ORS)
This might take up to 30 minutes.
If you want to do the requests without prepare_ors script, follow rapidspace-ORS.HowTo.Requests.Services.On.ORS
Add Instance node
After the services have been requested and the monitor base URL has been checked, you will be prompted to create the Core Network Instance node and add it to the SIM Card allocation supplies.
- Go to panel as rapidspace.ors, go the client's project, go to the core network, and click "Add Instance Node"
- Rename the instance node to "instance-node-orsXXX-core-network" to avoid confusion between the instance tree and the instance node
- Go to the allocation supplies list
- Find the allocation supply named "SIM Card" (it might be also named "Core Network Shared Instances")
- Click on it
- Add the instance node to the allocation supply, invalidate it and validate it again
Next the script will request the SIM Cards and check their connection parameters to wait and check until they have been attached to the core network.
Sending an ORS to a client
The next sections will explain how to configure and ship the ORS for a client.
This should be done BEFORE shipping the ORS
Double check the sale packing list before shipping the ORS
ORS5-Pack Dimensions (if you are shipping a 5-pack with ORS + 5 phones): 265 * 330 * 475mm , 8.6kg
Print DHL Label
- If you don't have already a DHL account for Rapidspace, ask Joanne to create it. For reference, Joanne will need to:
- After login MyDHL+, go to 'My Shipment Settings' on the top right navigation and click on 'Authorize Account Usage'
- Click on 'Grant new Authorization'
- Enter the name of your shipper, nickname and email address. You can also set the shipper's preferred language.
- Login to DHL using your account for Rapidspace
- Create a new shipment
- Fill the client's address (use Sale packing list as reference)
- Don't insure the package, don't set any price
- Put the Sale packing list reference as shipment reference
Send the welcome mail
Run the script to generate the welcome mail.
- Choose how the ORS is shipped: dhl, la_poste or in_person if the client already has the ORS or will get it in person
- Choose "new" if this is a client with a new panel account of a new client or "existing" if the client already has an account on the panel (if they already have purchased ORS)
- To get the token, login as rapidspace.ors to the panel, go to the client's project, click "Invite person", select "Customer" and click "Invite Person" button, then copy the generated token
If client hasn't bought root access:
laptop:~/WORKDIR/simpleran-tools# ./generate_ors_email.py {dhl,la_poste,in_person} {new_account,new_project,existing} tracking_number sale_order sale_packing_list token product_list
- {dhl,la_poste,in_person}: choose accordingly depending on how ORS was shipped
- {new_account,new_project,existing}:
- new_account: Choose this for a new client which never bought an ORS before
- new_project: Choose this if the project is new but client already has an account
- existing: Choose this if client already has an account and if project already existed before
- tracking_number : DHL / UPS / La Poste tracking number, for in_person you can just put XX (argument is still needed)
- sale_order: ERP5 Sale Order reference, (SO-XXXX)
- sale_packing_list: ERP5 Sale Packing List reference (SPL-XXXX)
- token: panel.rapid.space client project invite token
- product_list: ORS reference list (ex: ORS1 ORS3 ORS4)
Else for root access:
laptop:~/WORKDIR/simpleran-tools/oss# ./generate_ors_email.py -r -m MAC_ADDRESS -i PUBLIC_IPV6 -l {200,600} {dhl,la_poste,in_person} {new,existing} tracking_number sale_order sale_packing_list token product_list
-l : Put 200 for clients who bought SDK200 license, or 600 if they bought SDK600
Then copy paste the title in the email title and the html code in your email client in HTML source code mode and attach the sale packing list as PDF.