{"id":18695330,"url":"https://github.com/smartthingscommunity/st-schema-serverless-example","last_synced_at":"2025-11-08T13:30:37.392Z","repository":{"id":199258295,"uuid":"678984383","full_name":"SmartThingsCommunity/st-schema-serverless-example","owner":"SmartThingsCommunity","description":"Example ST Schema virtual device connector using AWS Lambda functions","archived":false,"fork":false,"pushed_at":"2024-05-15T15:07:47.000Z","size":5900,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":30,"default_branch":"main","last_synced_at":"2024-12-28T03:23:42.197Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SmartThingsCommunity.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-08-15T21:04:30.000Z","updated_at":"2024-05-15T15:07:52.000Z","dependencies_parsed_at":null,"dependency_job_id":"f144dd65-986a-4c76-8106-51d72388438b","html_url":"https://github.com/SmartThingsCommunity/st-schema-serverless-example","commit_stats":null,"previous_names":["smartthingscommunity/st-schema-serverless-example"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SmartThingsCommunity%2Fst-schema-serverless-example","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SmartThingsCommunity%2Fst-schema-serverless-example/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SmartThingsCommunity%2Fst-schema-serverless-example/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SmartThingsCommunity%2Fst-schema-serverless-example/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SmartThingsCommunity","download_url":"https://codeload.github.com/SmartThingsCommunity/st-schema-serverless-example/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239558906,"owners_count":19658927,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-07T11:14:40.270Z","updated_at":"2025-11-08T13:30:37.344Z","avatar_url":"https://github.com/SmartThingsCommunity.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"ST Schema Serverless Example\n============================\n\nThis reference application includes an ST Schema Cloud-to-Cloud (C2C) connector, an OAuth2 server for authenticating\nfrom the SmartThings mobile app, and a web UI for creating, deleting and controlling devices.\n\nThe app uses the [st-schema SDK](https://www.npmjs.com/package/st-schema), the [express](https://www.npmjs.com/package/express) web server, [EJS](https://ejs.co/), and the [Knockout](https://knockoutjs.com/documentation/introduction.html) UI library.\nIt's configured to be deployed to Amazon Web Services using the [Serverless](https://www.serverless.com/) framework.\nDeploying the app will create the necessary AWS resources including a DynamoDB table for storing devices, Lambda\nfunctions for the web server and ST Schema connector, and an API Gateway endpoint updating the Web UI using\na web socket connection.\n\nThe app allows users to create a number of virtual devices including switches,\ndimmers, tunable white bulbs, color bulbs, motions sensors, and open/close \nsensors.\n\n### Prerequisites\n\n- NodeJS 18.x or later installed\n- An [Amazon Web Services account](https://aws.amazon.com/)\n- The [AWS CLI](https://aws.amazon.com/cli/) installed and configured\n- The [Serverless](https://www.serverless.com/) framework installed\n- A [Samsung account](https://v3.account.samsung.com/dashboard/intro)\n- The [SmartThings CLI](https://github.com/SmartThingsCommunity/smartthings-cli) installed\n- The SmartThings mobile app (available from the [iOS App Store](https://apps.apple.com/us/app/smartthings/id1222822904) or [Google Play Store](https://play.google.com/store/apps/details?id=com.samsung.android.oneconnect))\n\n\n# File Structure\n\n* lib -- Example third party app classes\n  * Account.js -- Account domain object and password management\n  * connector.js -- The ST Schema connector\n  * db.js -- Reading and writing of devices and access tokens to DynamoDB\n  * device-service.js -- Proactive state callbacks\n  * mapping.js -- Mappings between ST Schema and the external representation of devices\n  * websockets.js -- Functions for sending device updates to the web UI\n* public -- Static web server files\n  * images -- images for use in web pages\n  * javascript\n    * devices.js -- View model object for a device\n    * devices.js -- Initializes the devices page and view model\n    * devicesviewmodel.js -- Top level view model for the page\n    * oauth.js -- Initializes the OAuth page\n    * property.js -- View model object for a device property\n  * stylesheets\n* routes -- Web application controllers\n  * devices.js -- Handles web-based device CRUD and control operations\n  * index.js -- Home page and web UI login\n  * oauth -- Handles login and OAuth authorization for ST mobile app\n  * schema -- ST Schema endpoint\n* views\n  * devices\n    * index.ejs -- The devices page\n  * oauth\n    * invalidauth.js -- Invalid authorization error page\n    * login.js -- The OAuth login page rendered in the SmartThings app\n  * error.ejs -- Web app error page\n  * index.ejs -- Web app landing page with a link to the devices web page\n  * login.ejs -- Web app login page\n* handler.js -- Defines the Lambda functions\n* package.json -- NPM package definition\n* serverless.yml -- Serverless framework configuration\n* serverless-env.js -- Customized serverless environment variables\n* serverless-env-example.yml -- Example serverless environment variables\n\n# Setup\n\n## Configure and deploy the web application\n\nClone this repository and change to the root directory of the project.\n```bash\ngit clone xxx\ncd xxx\n```\n\nCopy the `serverless-env-example.yml` file to `serverless-env.yml`.\n```bash\ncp serverless-env-example.yml serverless-env.yml\n```\n\nInstall the NPM modules.\n```bash\nnpm install\n```\n\nInstall the serverless framework if you have not already done so.\n```bash\nnpm install -g serverless\n```\n\nDeploy the application to AWS with the verbose option set to see the output from the serverless framework.\nYou only need to use the verbose option the first time you deploy the application, \nso that you can see the ARN of the schema connector Lambda function.\n```bash\nserverless deploy\n```\n\nThe serverless framework will print out the websocket endpoint and the URL of the deployed application and\nthe ARNs of the Lambda functions. For example:\n```\nendpoints:\n  wss://xxxxxxxx.execute-api.us-east-1.amazonaws.com/dev\n  website: https://xxxxxxxxxxxxxxxxxxxxxxxx.lambda-url.us-east-1.on.aws/\nfunctions:\n  connect: st-schema-serverless-example-dev-connect (7 MB)\n  disconnect: st-schema-serverless-example-dev-disconnect (7 MB)\n  schema: st-schema-serverless-example-dev-schema (7 MB)\n  website: st-schema-serverless-example-dev-website (7 MB)\n\nStack Outputs:\n  SchemaLambdaFunctionQualifiedArn: arn:aws:lambda:us-east-1:000000000000:function:st-schema-serverless-example-dev-schema:5\n  WebsiteLambdaFunctionUrl: https://xxxxxxxxxxxxxxxxxxxxxxxx.lambda-url.us-east-1.on.aws/\n  DisconnectLambdaFunctionQualifiedArn: arn:aws:lambda:us-east-1:000000000000:function:st-schema-serverless-example-dev-disconnect:36\n  ConnectLambdaFunctionQualifiedArn: arn:aws:lambda:us-east-1:000000000000:function:st-schema-serverless-example-dev-connect:36\n  WebsiteLambdaFunctionQualifiedArn: arn:aws:lambda:us-east-1:000000000000:function:st-schema-serverless-example-dev-website:36\n  ServiceEndpointWebsocket: wss://xxxxxxxx.execute-api.us-east-1.amazonaws.com/dev\n  ServerlessDeploymentBucketName: st-schema-serverless-exa-serverlessdeploymentbuck-xxxxxxxxxxxx\n```\n\nEdit your `serverless-env.yml` file and set the `API_GATEWAY_ENDPOINT` values from the wss endpoint printed out\nby the serverless framework (without the `wss://`). For example:\n```\nAPI_GATEWAY_ENDPOINT:\n  dev: \"xxxxxxxx.execute-api.us-east-1.amazonaws.com/dev\"\n```\n\nGive SmartThings permission to invoke your `schema` Lambda function using the ARN from the serverless\nframework output, minus the trailing version number. You can do this with the SmartThings CLI:\n```bash\nsmartthings schema:authorize arn:aws:lambda:us-east-1:000000000000:function:st-schema-serverless-example-dev-schema\n```\n\nOr you can do it with the AWS CLI:\n```bash\naws lambda add-permission \\\n--function-name arn:aws:lambda:us-east-1:000000000000:function:st-schema-serverless-example-dev-schema \\\n--statement-id smartthings \\\n--action lambda:InvokeFunction \\\n--principal 906037444270 \n```\n\n## Create your Connector with the SmartThings CLI\n\nTo create a connector using the SmartThings CLI, first install the CLI. If you have not yet logged into your \nSamsung account in the CLI, you will be prompted to do so when running the CLI commands below.\nCopy the following information into a JSON file, for example `myapp.json`. Replace the values with your own.\n```json\n{\n  \"appName\": \"ST Schema Serverless Example\",\n  \"partnerName\": \"ST Schema Serverless Example\",\n  \"schemaType\": \"st-schema\",\n  \"oAuthClientId\": \"a4a278fd-0ac1-47d9-b93a-987e3f401015\",\n  \"oAuthClientSecret\": \"830c120e-a791-453c-94b7-302fea58a823\",\n  \"oAuthAuthorizationUrl\": \"https://xxxxxxxxxxxxxxxxxxxxxxxx.lambda-url.us-east-1.on.aws/oauth/login\",\n  \"oAuthTokenUrl\": \"https://xxxxxxxxxxxxxxxxxxxxxxxx.lambda-url.us-east-1.on.aws/oauth/token\",\n  \"hostingType\": \"lambda\",\n  \"lambdaArn\": \"arn:aws:lambda:us-east-1:000000000000:function:st-schema-serverless-example-dev-schema\",\n  \"userEmail\": \"youremail@whatever.com\"\n}\n\n```\n\nThen create the connector using the CLI:\n```bash\nsmartthings schema:create -i myapp.json\n```\n\nThe CLI will print out the client ID and client secret values. Copy these into the `ST_CLIENT_ID` and `ST_CLIENT_SECRET` \nentries in the `serverless-env.yml` file.\n\n## Deploy your web application again\n\n```bash\nserverless deploy\n```\n\n## Create an account in your application\n\nVisit the website URL (`https://xxxxxxxxxxxxxxxxxxxxxxxx.lambda-url.xxxxxxxxx.on.aws/`) and click the _Get Started_ link.\nEnter an email address and password and click _Create New Account_. Once you are signed in, click the\n_Create your first device_ link to create a device. You can create more devices, delete devices, and log\nout using the [...] menu at the top of the page. \n\nThis web application represents a partner device application. The email and password do not need to be the same\nas your Samsung account (and the password should generally not be the same, for best security practices). The\napplication only interacts with SmartThings after you have installed an ST Schema connector.\n\n## Install your ST Schema Connector\n\nInstall the SmartThings mobile app from the [iOS App Store](https://apps.apple.com/us/app/smartthings/id1222822904)\nor [Google Play Store](https://play.google.com/store/apps/details?id=com.samsung.android.oneconnect),\nlog in with the same email address and password used for your developer workspace account, and \ncreate a location if you have not already done so.\n\nNext, use the CLI to create a [SmartThings Schema invitation](https://developer.smartthings.com/docs/devices/cloud-connected/st-schema-invites) \nfor your new integration: \n\n```bash \n$ smartthings invites:schema:create\n```\n\nThe CLI will step you through the invitation creation process and generate an `Accept URL`. Visit the `Accept URL` \nto install your integration to a location associated with your Samsung account. After completing the invitation \nacceptance process, your integration should now be visible from the SmartThings app when logged in with your Samsung account. \n\n### (Optional) Invite others to install and test your Connector \n\n[SmartThings Schema invitations](https://developer.smartthings.com/docs/devices/cloud-connected/st-schema-invites) allow you \nto invite other users to test your Schema integration.  \nWhen you are ready to distribute your Connector to internal testers, \nyou can use invitations to test and iterate your Connector with other users without \nneeding to publish to the SmartThings catalog. \nLearn more about invitations on our [developer documentation portal](https://developer.smartthings.com/docs/devices/cloud-connected/st-schema-invites).\n\n## Control devices from SmartThings and your web application\n\nAfter installing your connector, you should see your devices in the SmartThings mobile app. You can control them from the \nmobile app and from the web application. The status should be updated in both places.\n\nEach device in the mobile app has a button on the dashboard page that controls the main capability of the device. You \ncan control switches and trigger sensors using this button. If you tap on the device tile to the left of the button\nyou will see a device detail page that lets you see and control all capabilities of the device.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmartthingscommunity%2Fst-schema-serverless-example","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmartthingscommunity%2Fst-schema-serverless-example","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmartthingscommunity%2Fst-schema-serverless-example/lists"}