:orphan: Instrument Provisioning for Remote Access ========================================= Provisioning an instrument is the basic setup so an AirPhoton Instrument can reach the central management server via the COM100 or PC DataLink interface. For this to work correctly: * the instrument needs an unique record on the API Server * the instrument needs to be configured * the instrument needs to be connected to a COM100 * the COM100 needs to have an Internet connection API Server Setup ---------------- .. WARNING :: Keep in mind that there are two API Servers. For campaigns and deployments use ``api.airphoton.io``. If you simply want to play around, use ``sandbox.airphoton.io``. By default, AirPhoton pre-provisions end-user instruments on the production server. If you would like your instrument provisioned on the `sandbox` server, please contact support@airphoton.com. From a computer, navigate to the `production server portal`_ to manage your instruments. Use your API server account to log in. Navigate to *App* > *Instruments*, and select the instrument to be provisioned. At minimum, update the ``instrument password`` with a random, secure password. Instruments use their pre-assigned *serial number* and *passkey* for remote functionality. Other data fields such as *name*, *status*, and *info* are present for user reporting. .. IMPORTANT :: Keep a record of the each instrument's *instrument password* as this value will not be shown again. .. NOTE :: The *instrument password* cannot be longer than 59 ASCII characters. .. WARNING :: Do *not* change the *serial number*. While the server does allow it, this field needs to match the instrument reported serial number. .. _`production server portal`: http://api.airphoton.io/v1/portal/ Instrument Configuration ------------------------ .. NOTE :: Instrument configuration must be performed locally via USB. See AirPhoton's ``GN-7002-A Instrument Serial Port Manual`` for more details on electrical and computer setup. Connect to the instrument using a USB-B cable and serial terminal such as PuTTy. For an example command, type ``HELP`` to see a listing of commands, and try ``HELP=APIHOST`` to see a more detailed message on how to set the *api hostname*. We will configure the instrument using these commands ``NETNAME``, ``NETPASS``, ``APIPASS``, ``APIHOST``. Check ``HELP=`` for each one if you need some guidance. If you want to verify what setting already exists, simply type the command without value: ````. .. WARNING :: Due to embedded storage algorithms, *netname*, *netpass*, *apipass*, *apihost* need to be 59 ASCII characters or shorter. From the prior setup, configure the instrument's *remote credentials*. The serial number is pre-programmed at time of manufacture, but you will need to upload the *apipass*. .. code-block:: bash APIPASS= Verify the *apihost*, the API server's fully qualified domain name (FQDN), and if needed, change it. This setting should be the FQDN for the server on which you created or updated the instrument account. .. code-block:: bash APIHOST # if needed, change. APIHOST= The following settings configure the Internet (WiFi) connection to be used. At boot, the COM100 requests these settings from the instrument to reach the API Server. .. NOTE :: The WiFi SSID and key can be any valid combination, but if you are using an AirPhoton provided cell modem, please see inside the modem for *SSID* and *key*. .. code-block:: bash NETNAME # if needed, change. NETNAME= NETPASS # if needed, change. NETPASS= Instrument Setup and Internet ----------------------------- See instrument setup guide for more details, but in order to test *User's Computer* to *API Server* to *COM100* to *Instrument* and back, make sure the following are connected. 1. Instrument is assembled and powered 2. DataLink Cable (6 pin) from COM100 to Instrument 3. COM100 Power (2 pin) (wall power supply or aux. cable from station) The COM100 currently only gets the Internet (WiFi) credentials at boot. There is no power switch on the COM100, so you either need to cycle station power when using the aux. cable or un-plug/re-plug the wall power supply. Also, if you change the Internet credentials on the instrument (Step 2 above), you need to cycle the power on COM100 to use the new settings. Provision Test -------------- After following this sub-guide, test the connection. We recommend the :ref:`Example: Sending a Basic Command` example from the :ref:`API Server` documentation as this tests all of the different connections!