Simple Python ST Schema Connector

This ST Schema Connector project has been designed to deploy two server instances (OAuth and Webhook Schema Connector) that will interact altogether with the device reference encoded as a JSON Web Token.

In addition, this project has been developed on top of the Python's http.server built-in module and uses the SmartThings Schema Connector Python SDK to integrate virtual devices into the SmartThings platform.

---

Project scaffolding:

• run.py - Module used to call the OAuth and Webhook services.

• /lib

  • /oauth

    • data
      • user_information - Module that in charge of user registration and creation of JSON Web Tokens. It will create a .p file in reference of the pickle module used to save user information in binary form.
    • oauth_config
      • config - Module that loads the environment variables from the .env file.
    • public
      • login.html
    • app.py - Module that handles Http and provides the OAuth service.

  • /webhook

    • data
      • device_information - Module that get data from the .p files that contains the device information.
      • device_info.p - File that contains device information for Discovery Responses.
      • device_state_info.p - File that contains device information for State Refresh Responses.
      • device_info_ref.txt - Readable reference of the content at the device_info.p file.
      • device_state_info_ref.txt - Readable reference of the content at the device_state_info.p file.
    • webhook_config - Module that loads the environment variables from the .env file.
    • my_connector - Module that handles Interaction types with the help of the SmartThings Schema Connector Python SDK.
    • app.py - Module that handles Http and provides the Webhook service.

---

Project requirements:

• Python 3.6 or greater.
• SmartThings Developer Account.
• SmartThings App (developer mode active).

Package installation:

1. Clone this project and install its dependencies:

    git clone [email protected]:erickvneri/simple-python-schema-connector.git
    python3 -m pip install -r requirements.txt
   

2. To install the SmartThings Schema Connector Python SDK follow these instructions.

3. At your working directory, create a .env file following the example.env file (you can copy-paste the content of this last one to ease the process).

Deploying services locally:

To deploy both servers, you'll need two separate terminals.

1. To deploy the OAuth server, run the following command at your first terminal:

    python3 run.py --service oauth
   

2. To deploy the Webhook Schema Connector server, run the following command at your first terminal:

    python3 run.py --service webhook
   

Enable tunneling services:

To expose both apps at the World Wide Web, I recommend you to use localtunnel as it allows to deploy multiple tunneling instances with no payment needed.

As we did in the last step, you'll need two separate terminals to deploy both localtunnel instances.

1. Enable tunneling service for OAuth server at your third terminal:

    lt --port 5000 --print-requests
   

2. Enable tunneling service for Webhook server at your fourth terminal:

    lt --port 8000 --print-requests
   

Create your ST Schema Connector project:

1. Access your Developer Workspace.

2. Create your project following this sequence of steps:

   • New Project -> Device Integration -> SmartThings Cloud Connector -> SmartThings Schema Connector -> Name your project.

3. Click at Register App.

4. Select Webhook Endpoint and copy-paste the localtunnel url (port 8000) and include the /my-schema-connector endpoint as follows:

    https://example-webhook-url.loca.lt/my-schema-connector
   

5. Click Next to register your OAuth configuration. If you're using the dummy credentials from the example.env file, use the following values:

   • Client Id: dummy-client-id
   • Client Secret: dummy-client-secret

6. As OAuth endpoints, copy-paste the localtunnel url (port 5000) and include the /authorize and /token endpoints as follows:

   • Authorization URI: https://example-oauth-url.loca.lt/authorize
   • Token URI: https://example-oauth-url.loca.lt/token

7. (Optional) Fill the Scopes field and click Next.

8. Fill the App Display Name field.

9. To finalize, upload a 240x240 .png image and click Save.

Deploy your project at the SmartThings App:

1. From the Dashboard, tap the "+" sign and select "Device".
2. At the bottom of the "By device type" section, select "My Testing Devices".
3. Track your project and select it.
4. Once the Login page has been deployed, you'll be able to select a few example devices for demonstration.
5. Finalize the installation and test the example devices. By default, the Webhook server has enabled the logger instance from the SmartThings Schema Connector Python SDK, therefore, you'll get full detail of the interaction types received at your terminal.

---

To learn more about SmartThings Schema Connector integrations, please visit our main documentation or share your questions at our Community Forums.