Schema Devices and Custom Capabilities

[jody.albritton (Jody)]

Creating custom capabilties for schema devices

Using the SmartThings CLI and Developer Workspace

We are going to create a Cloud Connected Device using Schema and webhooks. Our base device will be a basic switch.

The first part of this tutorial will cover create the connector, oAuth server, and adding the Switch to SmartThings. The second part of the tutorial will cover adding a custom capability to this new device.

Prerequisites:

• Samsung Account
• Developer Workspace Access
• Developer Mode Enabled
• Glitch Account
• Text File

Step 1: Remix this Glitch account (connector)

1. Set the values in the .env file using .env-example as a guide.

2. Once the remixed app is up and running copy its URL to your text file.

3. Register the webhook url in SmartThings Developer Workspace and deploy it for testing.

Step 2: Remix this Glitch account (OAuth)

1. Edit the .env file to set your own client ID and secret, for example:

  EXPECTED_CLIENT_ID="somerandomvalueyouchoose"
  EXPECTED_CLIENT_SECRET="anotherrandomvalueyouchoose"
  AUTH_REQUEST_PATH="/oauth/login"
  ACCESS_TOKEN_REQUEST_PATH="/oauth/token"

Step 3: Run each of your newly remixed apps in their own browser window.

You should now have three browser windows open.

1. Developer Workspace
2. Remixed Connector
3. Remixed oAuth Server

Step 4: Register in the developer workspace

Name your Connector

Click Register App In the Cloud Connector Box

Click Webhook Endpoint

Enter your connector URL

Click Next

Now Move to the oAuth app tab from Step 2.

Create a Client ID and Secret in the .env file

Back in the workspace these are the ID and Secret you will use in the form.

"Client ID" = the client ID you created in step two
"Client Secret" = the client secret you created in step two
"Authorization URI" = your-glitch-project.glitch.me/oauth/login
"Token URI" =  your-glitch-project.glitch.me/oauth/token

Click Next

Edit your catalog entry. NOTE your image must be 240x240px

Click Next

WARNING - You need to copy the values from the screen

Edit the .env file for your connector app, using the copy button from this screen and copy the Client ID and Client Secret to their fields.

Click Go To Project Overview
Click Deploy to Test
Click Got It

Step 5: Create Your Starter Device Profile

Choose Option 2

Add a Device Profile

Create a new one

On this screen

Give your profile a name and description

Select “Switch” for the Device Type

Enter a random string for the Vendor ID

Click Add Capability

Find the Switch Capability, click add and close the window.

Click Next

Set the State to “Switch”
Set the Action to “Switch”

Click Create Device Profile

On the following screen copy your “Device Profile ID”

Step 6: Edit your connector.js file on the connector app tab

Step 7: Confirm that you can install this device in your mobile app

Put the SmartThings mobile app in developer mode and tap the “+” button at the top to add a device. Scroll down to My Testing Devices tap on it, and select your connector. Complete the OAuth login process and return to the Devices page. You will be prompted to complete the integration and your device will be added to the room.

[cjisndenial (CJ)]

@jody.albritton been waiting for this all summer, so pretty excited! I see you mention “part 2” in the opening of this post, but I can’t find it anywhere. Is it still forthcoming?

[jody.albritton (Jody)]

Coming this week. Were you able to create a device successfully using the above tutorial and can you provide any feedback, positive or negative? Thanks!

[cjisndenial (CJ)]

Jody I didn’t follow the specific instructions above because I already have a C2C connector setup on AWS using previous documentation/tutorials. And I’ve previously used the Developer Workspace to create custom Device Profiles. My issue is that my devices can’t quite be modeled right with the built-in capabilities. I was wondering if I could follow the other tutorial and use the new CLI to create custom capabilities and then maybe they would appear in Developer Workspace for use? I ran out of time to explore that this weekend.

[cdelasablonniere (Charles de la Sablonnière)]

Can’t wait for part 2!

Is it coming out soon?

Thanks for your help Jody.

[jody.albritton (Jody)]

Mobile app release triggered a regression. Fix is currently in QA/Internal testing and should be released to the public in the next two weeks. We are working hard to get custom capabilities to everyone using the new app with custom devices.

[cdelasablonniere (Charles de la Sablonnière)]

Ah ok, it is not just a matter of not knowing how to add custom capabilities, they are not available yet.

I’ll stop searching then!

Thanks

[cdelasablonniere (Charles de la Sablonnière)]

@jody.albritton
Is it possible now to create custom capabilities using Cloud Connector Schema Device profile?

I see a lot of posts about problems with custom capabilities, but they all seem to be related to DTH in IDE.

Thanks for your help,

Charles

[jody.albritton (Jody)]

@cdelasablonniere

Is it possible now to create custom capabilities using Cloud Connector Schema Device profile?

Yes it is. It works much the same way as the DTH but with device profile instead. Since there was a regression I left that part of the tutorial off, I will add it back as soon as I can.

[cdelasablonniere (Charles de la Sablonnière)]

Thanks @jody.albritton,

I have a couple of questions regarding Smartthings Schema Device Profiles:

1. Can you point me in the right direction for creating custom capabilities ?
Does it involve to manually modify the huge UI Manifest? I had a look at the documentation and I do not see how they fit together.

2. UI Display in Dashboard
My UI Display in Device Profile is setup like this:

But in the app it shows like this:

Any idea why?

3. Unable to use PH Measurement capability
I added the PH Measurement capability:

but it never shows up in the app detail page.
I also noticed the PH Measurement is not listed in the Capabilities Reference, should I be able to add it or not?

Thanks for your help,

Charles

[nayelyz (SmartThings Developer Support)]

Hello @cdelasablonniere,

@cdelasablonniere

1. Can you point me in the right direction for creating custom capabilities ?

When you create a custom capability and its presentation, you can see it in the list when creating your device profile, which will generate the device configuration based on each capability’s presentation.

@cdelasablonniere

2. UI Display in Dashboard

The messages “connected” or “checking status” appears if the capability in dashboard view (in this case temperatureMeasurement) has a null value.

@cdelasablonniere

3. Unable to use PH Measurement capability

For this capability, I could replicate the issue and I will document it and investigate more about it.

[cdelasablonniere (Charles de la Sablonnière)]

Thanks for your reply @nayelyz,

When you create a custom capability and its presentation, you can see it in the list when creating your device profile, which will generate the device configuration based on each capability’s presentation

Where do I create the custom capability and its presentation? Is it somewhere in the Developer Workspace? How do I get it to appear in the list?
When I look at the custom capabilities documentation, it is not mentionned.

The messages “connected” or “checking status” appears if the capability in dashboard view (in this case temperatureMeasurement) has a null value

The temperatureMeasurement does not have a null value, but “connected” still appears:

For this capability, I could replicate the issue and I will document it and investigate more about it.
Thank you for investiguating

Thanks for your help,

Charles

[nayelyz (SmartThings Developer Support)]

Hi @cdelasablonniere,

@cdelasablonniere

Where do I create the custom capability and its presentation?

You can use the SmartThings CLI, see this post where you can find documentation about the installation and commands; or API requests using a tool such as Postman (refer to the SmartThings API document).

@cdelasablonniere

The temperatureMeasurement does not have a null value, but “connected” still appears

Maybe some information was cached, so try updating the friendlyName and externalDeviceID in the discovery response of the Schema connector:
addDevice(externalDeviceID, friendlyName, deviceHandlerType)

[cdelasablonniere (Charles de la Sablonnière)]

Hi @nayelyz,

Things are progressing I guess

Maybe some information was cached, so try updating the friendlyName and externalDeviceID in the discovery response of the Schema connector:
addDevice(externalDeviceID, friendlyName, deviceHandlerType)

I changed the externalDeviceID and friendly Name, but I still have the same result even after deleting and re-adding the device in Smartthings app.

You can use the SmartThings CLI, see this post where you can find documentation about the installation and commands; or API requests using a tool such as Postman (refer to the SmartThings API document).

• I installed the cli from here
• Then I tried to create a custom capability, but I got an authentication error:
  
  
• I found the CLI documentation and it talks about requesting an access token. I tried that but the CLI I have does not recognize that command:
  
• I then saw in the CLI documentation that I can download the CLI from the Developer Workspace:
  
  
  
  But I do not have “Tools” menu in my Developer Workspace.

So my questions are:

• Are there different versions of the CLI ?
• Why the one I got does not recognize the “request-token” command?
• Am I suppose to have a “Tools” menu in my Developer Workspace?

Thanks for your help, it is appreciated.

Charles

[nayelyz (SmartThings Developer Support)]

Hi @cdelasablonniere,

The error you get is due to the lack of authorization, which can be done by:

1. Creating the YAML file mentioned in the configuration part of the readme. Example of the file content:

default:
          token: xxx-xxx-xxx

2. Adding the --token parameter in the command. For example:

smartthings devices --token=xxx-xxx-xxx

You will be using the Personal Access Token created in https://account.smartthings.com/tokens.

Also, to guide you using the commands available, the CLI provides a description of the command if you include --help. Example

smartthings devices --help

I will share your feedback about the documentation to continue improving it, thank you.

[cdelasablonniere (Charles de la Sablonnière)]

Hello @nayelyz, thank you for your help^.

I am able to create a custom capability, and I can add it to my device profile in the Developer Workspace.

Nothing is displayed in the Smartthings app though.

Here is my custom capability:

{
"id": "summerweather37297.orpmeasurement",
"version": 1,
"status": "proposed",
"name": "ORPMeasurement",
"attributes": {
    "ORP": {
        "schema": {
            "type": "object",
            "properties": {
                "value": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 1000
                },
				"unit":{
					"type": "string",
					"enum": [
						"mV"
					],
				}	
            },
            "additionalProperties": false,
            "required": [
                "value"
            ]
        },
        "enumCommands": []
    }
},
"commands": {}
}

and presentation:

{
"dashboard": {
    "states": [
        {
            "label": "{{orpmeasurement.value}} {{orpmeasurement.unit}}"
        }
    ],
    "actions": [],
    "basicPlus": []
},
"detailView": [
    {
        "label": "ORP",
        "displayType": "numberField",
		"numberField": {
			"value": "orpmeasurement.value",
			"unit": "orpmeasurement.unit",
			"command": []
		},
    },
],
"id": "summerweather37297.orpMeasurement",
"version": 1
}

The CLI rejects the presentation because the “command” section is malformed, but I have no commands to write.

What am I doing wrong?

Charles

[zldxkdlrj_dlcmaldml (It'sme Itsumi)]

I suppose if you don’t need to have input from user, which mean just want to show a string, you should use state, not numberField.
Otherwise you can add setter into capability and write that into command than you can receive input from user.

I’m not sure it’s a just my little guess (*/ω＼*).

[cdelasablonniere (Charles de la Sablonnière)]

Thanks for the tip @zldxkdlrj_dlcmaldml,

My capability hasn’t changed, it look like this:

{
"id": "summerweather37297.orpmeasurement",
"version": 1,
"status": "proposed",
"name": "ORPMeasurement",
"attributes": {
    "ORP": {
        "schema": {
            "type": "object",
            "properties": {
                "value": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 1000
                },
				"unit":{
					"type": "string",
					"enum": [
						"mV"
					],
				}	
            },
            "additionalProperties": false,
            "required": [
                "value"
            ]
        },
        "enumCommands": []
    }
},
"commands": {}
}

and my presentation now looks like this:

{
"dashboard": {
    "states": [
        {
            "label": "{{orpmeasurement.value}} {{orpmeasurement.unit}}"
        }
    ],
    "actions": [],
    "basicPlus": []
},
"detailView": [
    {
        "label": "ORP",
        "displayType": "state",
		"state": {
		    "label": "{{orpmeasurement.value}} {{orpmeasurement.unit}}",
			"unit": "orpmeasurement.unit",
		},
    },
],
"id": "summerweather37297.orpMeasurement",
"version": 1
}

The documentation doesn’t help much and the error message I get from the CLI when I try to create my presentation is useless:

I am trying to simply display a value here, nothing fancy, no actions…

@nayelyz : can you help me with that? What is missing in my presentation for it to work?

Thanks in advance,

Charles

[philh30]

Your attribute is ORP, so use ORP.value and ORP.unit in your capability presentation.

[zldxkdlrj_dlcmaldml (It'sme Itsumi)]

@philh30

Your attribute is ORP, so use ORP.value and ORP.unit in your capability presentation.

yes as @phiilh30 said,
formatting name should be {{<ATTRIBUTE_NAME>.[vlaue | unit]}}
so not {{orpmeasurement.value}} , but {{ORP.value}} .