{"id":13341682,"url":"https://github.com/dwettstein/comfortbox-api-services","last_synced_at":"2025-03-11T22:31:21.875Z","repository":{"id":73658690,"uuid":"73394475","full_name":"dwettstein/comfortbox-api-services","owner":"dwettstein","description":"Repository for my Master's thesis: RESTful services and automation for comfort-oriented smart devices","archived":false,"fork":false,"pushed_at":"2021-03-16T14:20:34.000Z","size":1048,"stargazers_count":1,"open_issues_count":3,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-10-24T10:07:03.219Z","etag":null,"topics":["api","comfortbox","iot","iot-framework","sensors","web-of-things"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dwettstein.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2016-11-10T15:24:03.000Z","updated_at":"2018-07-04T16:09:22.000Z","dependencies_parsed_at":"2023-05-20T06:45:49.163Z","dependency_job_id":null,"html_url":"https://github.com/dwettstein/comfortbox-api-services","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dwettstein%2Fcomfortbox-api-services","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dwettstein%2Fcomfortbox-api-services/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dwettstein%2Fcomfortbox-api-services/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dwettstein%2Fcomfortbox-api-services/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dwettstein","download_url":"https://codeload.github.com/dwettstein/comfortbox-api-services/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243125159,"owners_count":20240263,"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":["api","comfortbox","iot","iot-framework","sensors","web-of-things"],"created_at":"2024-07-29T19:25:43.182Z","updated_at":"2025-03-11T22:31:21.869Z","avatar_url":"https://github.com/dwettstein.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# comfortbox-api-services\nThis is the source code repository for my Master's thesis project: RESTful services and automation for comfort-oriented smart devices.\n\nIn a nutshell, the goal of this project is to build up proper data-storage and a well-defined RESTful API for ComfortBoxes. Furthermore, I want to add some additional value by allowing to integrate a ComfortBox into Node-RED workflows (see repository [node-red-contrib-comfortbox](https://github.com/dwettstein/node-red-contrib-comfortbox)).\n\nIf you are more interested in the ComfortBox itself, please have a look at the GitHub repository here:  https://github.com/DurandA/comfortbox\n\n### Big picture\n\u003cimg src=\"./docs/images/big_picture.png\" alt=\"Big picture\" width=\"500px\"/\u003e\n\n### Screenshots\n| RabbitMQ                                | KairosDB                                | API Explorer                                    | Grafana                               |\n|-----------------------------------------|-----------------------------------------|-------------------------------------------------|---------------------------------------|\n| ![RabbitMQ](./docs/images/rabbitmq.png) | ![KairosDB](./docs/images/kairosdb.png) | ![API Explorer](./docs/images/api_explorer.png) | ![Grafana](./docs/images/grafana.png) |\n\n\n---\n## Installation\nFor setting up RabbitMQ, KairosDB and (optionally) Grafana, take a look at the [server documentation](./docs/setup_server.md).\n\nAs the ComfortBox API is a Node.js application, you need to install Node.js in advance of course. Please have a look at their documentation for that: [Installing Node.js via package manager](https://nodejs.org/en/download/package-manager/#debian-and-ubuntu-based-linux-distributions)\n\nBefore you install the ComfortBox API, install the database with the following commands:\n\n```bash\nsudo apt-get install postgresql\n\nsu postgresql\n\ncreateuser -P comfortboxapi\n# Enter the password (e.g. comfortboxapi)\ncreatedb comfortboxapi\n\npsql\n# postgres=# grant all privileges on database comfortboxapi to comfortboxapi;\n# \\q\n```\n\nInstalling the ComfortBox API itself is easily done:\n- Copy or clone the repository\n- Install the dependencies by running `npm install`\n\n### Configuration\nAfter finishing the complete server installation, you need to configure the API services by editing the following two files, before you can use it.\n- `./server/config.json` \\- Update the values for:\n    - defaultUsername\n    - defaultPassword\n    - defaultEmail\n    - defaultAccessToken\n    - certificatePath\n    - privateKeyPath\n    - rabbitMqServer\n    - pathToKairosBindings\n    - \\[Optional\\] host, port, url\n- `./server/datasources.json` \\- Update the values for:\n    - ParticleAPI Authorization ([Bearer access token](https://docs.particle.io/reference/api/#generate-an-access-token) from account with your ComfortBox devices)\n    - KairosDB baseURL (hostname of certificate)\n    - KairosDB Authorization\n    - KairosDB url for each operation (hostname of certificate)\n- `./server/datasources.production.json` \\- Update the values for (not needed if you have setup the DB as written above):\n    - DB (PostgreSQL)\n\n### Run it\nDuring development you can run the API with `node .` or `nohup node . \u0026`.\n\nHowever, for production I recommend setting up a _systemd_ service using the example [comfortbox-api.service](./configs/comfortbox-api.service):\n1. If the path to the `node` command is not `/usr/bin/node`, update it with the value from `which node`\n2. Copy the file to the `/etc/systemd/system` directory\n3. Reload daemon: `sudo systemctl daemon-reload`\n4. Enable autostart: `sudo systemctl enable comfortbox-api.service`\n5. Start the service: `sudo systemctl start comfortbox-api.service`\n6. Check the status with `sudo systemctl status comfortbox-api.service`\n\n#### Production\nBefore running the API in production, you have to create the DB tables by running the script `automigrate.js`:\n\n```bash\nnode bin/automigrate.js\n```\n\n\n---\n## How to use the API\nFirst, have a look at the API Swagger documentation on `https://localhost:3000/explorer/` (change localhost to your hostname if needed).\nEvery request to the API needs to be authenticated with a token. Initially, you can use the default user or token defined in `./server/config.json`.\n\n### Register a new box\nBefore you can configure a ComfortBox or query data from it, you need to register it within the API.\nYou can do that by requesting `POST /ComfortBoxes` with the necessary data from your ComfortBox (at least the Particle ID of your device).\n\nIf your ComfortBox is already configured to send its messages to the MQTT installation of the API service, then it will be auto-registered as soon as it sends the `comfort.{{particleId}}.online` message.\n\n### Set MQTT host\nAfter the registration of a ComfortBox to the API, you can configure it.\nAs an example, you can set the MQTT host by requesting `POST /ComfortBoxes/{id}/setMqttHost` along with the host and port of the MQTT installation.\n\n### Query data\nAs soon as the registered ComfortBox sends the `comfort.{{particleId}}.online` message to the MQTT installation of the API service, the message queues and bindings will be created and you can query the device's data afterwards.\nTo see which metrics of a device are available simply request `GET /ComfortBoxes/{id}/getMetricNames`. Then you can query a metric by requesting `POST /ComfortBoxes/queryMetricData` and the corresponding metric name.\n\n\n---\n## Use the API services within your Node-RED flows\nFor using the API services within Node-RED workflows, have a look at the repository [node-red-contrib-comfortbox](https://github.com/dwettstein/node-red-contrib-comfortbox). There, you can also find some example flows.\n\n\n---\n## Development - Run the tests\nFor running the unit tests, just run `npm install` and `npm test` or directly `./node_modules/.bin/mocha` in the root folder.\n\nThe tests use the following libraries:\n- [mocha](https://mochajs.org/)\n- [chai](http://chaijs.com/)\n- [supertest](https://github.com/visionmedia/supertest)\n\nInspired by: https://stackoverflow.com/questions/35005001/loopback-testing-with-supertest-mocha-and-models#35256151\n\n---\nThe API is created with [LoopBack](http://loopback.io).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdwettstein%2Fcomfortbox-api-services","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdwettstein%2Fcomfortbox-api-services","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdwettstein%2Fcomfortbox-api-services/lists"}