{"id":16689218,"url":"https://github.com/sskorol/alexa-middleware","last_synced_at":"2025-05-15T10:31:16.034Z","repository":{"id":40733360,"uuid":"185037269","full_name":"sskorol/alexa-middleware","owner":"sskorol","description":"Sample Middleware service for routing requests between Alexa and micro-controllers.","archived":false,"fork":false,"pushed_at":"2024-01-11T08:55:11.000Z","size":534,"stargazers_count":3,"open_issues_count":3,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-29T21:33:02.785Z","etag":null,"topics":["alexa","expressjs","middleware","mosquitto","mqtt","pm2","smarthome","smarthome-skill","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sskorol.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-05-05T13:48:03.000Z","updated_at":"2023-07-25T08:18:13.000Z","dependencies_parsed_at":"2024-11-19T11:43:46.241Z","dependency_job_id":"e262b995-01e6-45b0-a6a7-0263035b47f0","html_url":"https://github.com/sskorol/alexa-middleware","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sskorol%2Falexa-middleware","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sskorol%2Falexa-middleware/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sskorol%2Falexa-middleware/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sskorol%2Falexa-middleware/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sskorol","download_url":"https://codeload.github.com/sskorol/alexa-middleware/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254322819,"owners_count":22051672,"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":["alexa","expressjs","middleware","mosquitto","mqtt","pm2","smarthome","smarthome-skill","typescript"],"created_at":"2024-10-12T15:47:32.219Z","updated_at":"2025-05-15T10:31:13.501Z","avatar_url":"https://github.com/sskorol.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Alexa Middleware Service\n\nThis repository contains a simple implementation of a middleware layer between Alexa and Arduino-like micro-controllers.\n\nSee [Alexa Smart Home Skill Template](https://github.com/sskorol/alexa-smart-home-skill-template) for details.\n\n## Installation and Startup\n\nRun the following command to setup required dependencies:\n\n```bash\nnpm install\n``` \n\nGenerate a self-signed certificate via [OpenSSL](https://www.openssl.org/) tool (or just use your own existing certificate).\n\nPut certificates into **./src/core/tls** folder. Names could be configured within **./src/utils/Constants.ts**.\n\nSetup [Mosquitto](https://mosquitto.org/) MQTT broker for routing messages between micro-controllers and middleware layer.\n\nNote that it's recommended to protect your broker with at least basic credentials.\n\nCreate **.env** file in the root of the project with the following content:\n\n```dotenv\nMIDDLEWARE_PORT=\nMQTT_USERNAME=\nMQTT_PASSWORD=\nROOT_TOPIC=home/#\nDEVICES_TOPIC=home/devices\nDEVICE_TOPIC_PREFIX=home/device\nSTATUS_TOPIC=home/middleware/status\n```\n\nFeel free to put your own values here.\n\nNote that by default Middleware layer is configured to listen all the messages from within **ROOT_TOPIC**.\n\n**DEVICES_TOPIC** is used for publishing an extensive information about available devices in you local network. Note that all the messages must follow the json format described in **./src/core/index.ts**.\n\nBasically, all the micro-controllers will use Alexa-compatible messages' format to avoid any additional transformations while interacting with a Smart Home Skill. You can check the following [repository](https://github.com/sskorol/arduino-alexa-bridge) to simplify required configuration stuff.\n\n**DEVICES_TOPIC_PREFIX** is used to access individual device state. It's concatenated with device id (**endpointId**) and **/state** suffix in runtime.\n\n**STATUS_TOPIC** is useful for tracking middleware MQTT client's state via so-called **will** feature. This topic will be notified when a client goes online/offline.  \n\nTo start Middleware in a development mode, use the following command:\n\n```bash\nnpm run start\n```\n\nNote that in this mode you'll see all the requests / responses in the console log. Moreover, any code updates will immediately trigger rebuild and restart process. \n\nTo run this Middleware in a production mode (e.g. on Raspberry Pi environment) you may want to setup [pm2](https://pm2.io/doc/en/runtime/overview/?utm_source=pm2\u0026utm_medium=website\u0026utm_campaign=rebranding) tool globally first.\n\nThe following command will help to wrap some common startup / shutdown operations:\n```bash\nnpm run start-prod\nnpm run stop-prod\n```\n\n## Endpoints\n\nUse the following endpoints to interact with Alexa Smart Home Skill:  \n\n - [GET] **/api/devices/stateReports**: returns actual states collected from available devices in your local network.\n - [GET] **/api/devices/:id/state**: returns a state report form requested device.\n - [GET] **/api/devices**: returns all available devices in you local network in Alexa-compatible for discovery format.\n - [DELETE] **/api/devices**: clears an in-memory array of available devices.\n - [POST] **/api/devices/:id**: sends an MQTT command to specified device.\n \n## Flow\n\nLet's consider the following scenario: user wants to turn on the light.\n\nLight bubble might be controlled by NodeMCU board via relay or RF transmitter.\n\nIf micro-controller sends the following json to **home/devices** topic, Middleware will put it into in-memory storage for further usage by Alexa Smart Home Skill. \n\n```json\n[\n  {\n    \"endpointId\": \"lobby_lamp_1\",\n    \"friendlyName\": \"light\",\n    \"description\": \"Lobby Lamp 1\",\n    \"manufacturerName\": \"Home\",\n    \"cookie\": {},\n    \"displayCategories\": [\n      \"LIGHT\"\n    ],\n    \"capabilities\": [\n      {\n        \"type\": \"AlexaInterface\",\n        \"interface\": \"Alexa.PowerController\",\n        \"version\": \"3\",\n        \"properties\": {\n          \"supported\": [\n            {\n              \"name\": \"powerState\"\n            }\n          ],\n          \"proactivelyReported\": true,\n          \"retrievable\": true\n        }\n      },\n      {\n        \"type\": \"AlexaInterface\",\n        \"interface\": \"Alexa\",\n        \"version\": \"3\"\n      },\n      {\n        \"type\": \"AlexaInterface\",\n        \"interface\": \"Alexa.EndpointHealth\",\n        \"version\": \"3\",\n        \"properties\": {\n          \"supported\": [\n            {\n              \"name\": \"connectivity\"\n            }\n          ],\n          \"proactivelyReported\": true,\n          \"retrievable\": true\n        }\n      }\n    ]\n  }\n]\n```\n\nWhen user first activates a skill and run devices' discovery, Smart Home Skill calls [DiscoveryHandler](https://github.com/sskorol/alexa-smart-home-skill-template/blob/development/src/core/DiscoveryHandler.ts), which then requests devices from our Middleware **/api/devices** endpoint.\n\nWhen user says **Alexa, light on** (assuming the mentioned above friendly name in json), Smart Home Skill calls [PowerHandler](https://github.com/sskorol/alexa-smart-home-skill-template/blob/development/src/core/PowerHandler.ts), which then sends a power control command, e.g.\n\n```json\n[\n  {\n\t\"command\":\"TurnOn\",\n  \t\"state\":true\n  }\n]\n```\n \nto our Middleware -\u003e **/api/devices/lobby_lamp_1** endpoint.\n\nThis command is published to individual **home/device/lobby_lamp_1** topic, which our NodeMCU board is subscribed to.\n\nMicro-controller parses json message and executes the requested command via relay or RF transmitter. \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsskorol%2Falexa-middleware","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsskorol%2Falexa-middleware","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsskorol%2Falexa-middleware/lists"}