Getting Started

1. Complete Pre-Installation Requirements

The requirements below are the base components and infrastructure that one needs for before setting up and running the GATE-Ware application.

1. Your Conduit must be connected and initial configuration steps according to Multitech’s instructions here.
2. You must have the GATE-Ware distribution on your computer. *
3. You must have a valid GATE-Ware license. *
4. The backend (AWS, Azure or MQTT) must be configured and credentials generated according to the provider’s instructions. GATE-Ware can be run without cloud TLS credentials, but they are strongly recommended.

* For software distributions and licenses, please request an evaluation license at eval.gateware.io or contact us directly at support@threelabs.io.

2. Create a Configuration File

Whether you choose a cloud provider or roll-your-own offline solution, GATE-Ware has you covered with appropriate with “base configurations” for each scenario.

Base configuration step-by-step:

A “base configuration” is nothing more than the minimum set of configuration attributes required by GATE-Ware. For complete information on all configuration options, please see the Attributes section.

1. Identify your cloud below (or custom/roll-your-own MQTT).
2. Cut and paste the associated JSON content into a new file named: gateware.json.
3. Replace the example credentials, endpoint, port and license key with your cloud-specific and purchased key values.

MQTT - Including AWS IoT Core

{
  "backend_mqtt_endpoint_host": "broker.example.com",
  "gateware_license_key": "abcd="
}

{
  "backend_mqtt_ca": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
  "backend_mqtt_endpoint_host": "broker.example.com",
  "backend_mqtt_endpoint_port": 8883,
  "backend_mqtt_password": "password",
  "backend_mqtt_use_tls": true,
  "backend_mqtt_username": "username",
  "gateware_license_key": "abcd="
}

{
  "backend_mqtt_ca": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
  "backend_mqtt_client_cert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
  "backend_mqtt_endpoint_host": "broker.example.com",
  "backend_mqtt_endpoint_port": 8883,
  "backend_mqtt_private_key": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----",
  "backend_mqtt_use_tls": true,
  "gateware_license_key": "abcd="
}

Microsoft Azure IoT

{
  "backend_azure_dps_scope_id": "0ne00000000",
  "backend_azure_sas_primary_key": "000000000000000000000000000000000000000000000=",
  "backend_azure_sas_secondary_key": "000000000000000000000000000000000000000000000=",
  "backend": "azure",
  "gateware_license_key": "abcd="
}

{
  "backend_azure_dps_group_enrollment_registration": true,
  "backend_azure_dps_scope_id": "0ne00000000",
  "backend_azure_sas_primary_key": "000000000000000000000000000000000000000000000=",
  "backend_azure_sas_secondary_key": "000000000000000000000000000000000000000000000=",
  "backend": "azure",
  "gateware_license_key": "abcd="
}

{
  "backend_azure_dps_scope_id": "0ne00000000",
  "backend_azure_dps_group_enrollment_registration": true,
  "backend_azure_sas_primary_key": "000000000000000000000000000000000000000000000=",
  "backend_azure_sas_secondary_key": "000000000000000000000000000000000000000000000=",
  "backend": "iotcentral",
  "gateware_license_key": "abcd="
}

3. Install GATE-Ware on your Conduit

There are three options for installing GATE-Ware on your Conduit. Each may be more or less suitable depending on your particular need.

For example, you may decide to use Direct (SSH) for installing during iterative development or manufacturing.

For deployed units, DeviceHQ may be the best option - this method can also be used for converting already deployed Conduits to using GATE-Ware.

Direct (SSH)

The included install-to-conduit.sh script will install the GATE-Ware distribution to the Conduit and automatically start the main application. The script will also configure the Conduit to automatically run GATE-Ware on boot.

1. Double check that you’ve created your configuration file: gateware.json. See section: Create a Configuration File above.
2. Copy the gateware.json file to the gateware/config directory in your GATE-Ware distribution.
3. Substituting your credentials and Conduit IP address, use the following commands to install GATE-Ware to the Conduit:

% export CONDUIT_USER="admin"
% export CONDUIT_PASS="ExamplePassword123"
% ./install-to-conduit.sh gateware 192.168.2.1

Direct (Conduit Web Interface)

1. Double check that you’ve created your configuration file: gateware.json. See section: Create a Configuration File above.
2. Copy the gateware.json file to the gateware/config directory in your GATE-Ware distribution.
3. Use the following command to create a GATE-Ware distribution archive:

cd gateware
tar --hard-dereference -hczf ../gateware.tar.gz *

4. Browse to the Conduit’s web interface and navigate to the Apps page.
5. Click the + Add Custom App link on the top-right of the page.
6. Enter the following information:
   • App ID: GATE-Ware
   • App Name: GATE-Ware
   • Choose File: Select the gateware.tar.gz file you created in step 3.

DeviceHQ

1. Double check that you’ve created your configuration file: gateware.json. See section: Create a Configuration File above.
2. Use the following command to create a GATE-Ware distribution archive:

cd gateware
tar --hard-dereference -hczf ../gateware.tar.gz *

3. Navigate to the DeviceHQ Developer Page and log in.
4. Click the + Upload App button on the top-right of the page.
5. Choose File: Select the gateware.tar.gz file you created in step 2.
6. Click the GATE-Ware app in the list of apps.
7. Click the Configuration tab.
8. Click the + Upload Configuration button.
9. Click the Choose File button and select the gateware.json file you created in step 1.
10. Enter a helpful description for the configuration file.
11. Navigate to the DeviceHQ Device Page and select the Conduit you want to install GATE-Ware on.
12. Click Schedule -> Install App -> GATE-Ware.
13. Choose the App Configuration you uploaded in step 9.

The next time your device checks into DeviceHQ, GATE-Ware will be installed and start automatically. You can also force a check in to shorten the wait time.