{"id":20496338,"url":"https://github.com/bytemind-de/nodejs-client-extension-interface","last_synced_at":"2025-04-13T18:21:05.803Z","repository":{"id":34300258,"uuid":"175800406","full_name":"bytemind-de/nodejs-client-extension-interface","owner":"bytemind-de","description":"Node.js CLEXI is a Websocket server that extends connected clients with additional features of the OS (e.g. Bluetooth beacon scanning, GPIO control, etc.).","archived":false,"fork":false,"pushed_at":"2022-04-28T17:22:25.000Z","size":89,"stargazers_count":4,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-10-12T09:26:43.767Z","etag":null,"topics":["beacon-scanner","bluetooth","client-server","duplex-communication","gpio","led","node-js","raspberry-pi","spi","websocket"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/clexi","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/bytemind-de.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}},"created_at":"2019-03-15T10:36:40.000Z","updated_at":"2023-02-21T18:27:16.000Z","dependencies_parsed_at":"2022-08-08T00:15:47.130Z","dependency_job_id":null,"html_url":"https://github.com/bytemind-de/nodejs-client-extension-interface","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytemind-de%2Fnodejs-client-extension-interface","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytemind-de%2Fnodejs-client-extension-interface/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytemind-de%2Fnodejs-client-extension-interface/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytemind-de%2Fnodejs-client-extension-interface/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bytemind-de","download_url":"https://codeload.github.com/bytemind-de/nodejs-client-extension-interface/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248758961,"owners_count":21157063,"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":["beacon-scanner","bluetooth","client-server","duplex-communication","gpio","led","node-js","raspberry-pi","spi","websocket"],"created_at":"2024-11-15T18:06:38.952Z","updated_at":"2025-04-13T18:21:05.756Z","avatar_url":"https://github.com/bytemind-de.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Node.js CLEXI\nNode.js CLEXI is a lightweight **cl**ient **ex**tension **i**nterface that enhances connected clients with functions of the underlying operating system using a duplex, realtime Websocket connection.  \n  \nCurrently available extensions (activate via settings):\n* clexi-broadcaster - a simple **Websocket message** broadcaster\n* clexi-http-events - receives **HTTP events** via '/event' **endpoint** and broadcasts them via the Websocket connection\n* ble-beacon-scanner - scans for **Bluetooth BLE beacons** and broadcasts their data\n* runtime-commands - execute **runtime commands**\n* gpio-interface - register **Raspberry Pi GPIO** items (buttons, LEDs, pins, SPI, custom), send and receive data\n\nCLEXI works as a web-server as well and can host the client application if required (e.g. just put the files in the www folder).\n\n## Using as node module\n\nInstall via `npm install clexi` (tested under Linux, please see requirements section below) then build your own server like this:\n```\n'use strict'\nconst settings = {\n\tssl: false\n}\nconst Clexi = require('clexi')(settings);\nClexi.start();\n```\nThis will run fastify with Websocket and static file support and expose the CLEXI xtensions.\nCustom settings can be used to implement additional, self-made xtensions as well, e.g.:\n```\nconst settings = {\n\tport: 9000,\n\thostname: '0.0.0.0',\n\tid: 'my-clexi-server-123',\n\twwwPath: '/home/pi/clexi-www',\n\tcustomXtensionsPath: '/home/pi/clexi-xtensions',\n\tcustomXtensions: ['my-xtension']\n}\n```\nSee client and extensions section below to get more info.\n\n## Raspberry Pi 4 installation\n\nRequirements:  \n* Node.js (v0.9.0+ should **use 14** - v0.8.2 was tested with 9.11.2 and 10.15.3)\n* Some packages for Bluetooth etc.: `sudo apt-get install bluetooth bluez libbluetooth-dev libudev-dev libnss3-tools libcap2-bin openssl procps`\n* To install Node packages you might need: `sudo apt-get install build-essential`\n* SSL certificates for HTTPS (you can use the included script to generate self-signed)\n\n### Install Node.js 14\n\nYou can use the official script:\n```\ncurl -fsSL https://deb.nodesource.com/setup_14.x | sudo -E bash -\nsudo apt-get install -y nodejs\n```\n\n### Install CLEXI\n\nClone the repository to the folder 'clexi', enter the folder and run `npm install`:  \n```\ngit clone https://github.com/bytemind-de/nodejs-client-extension-interface.git clexi\ncd clexi\nnpm install\n```  \nDecide which hostname you want to use for your server. Default is `localhost` but I usually prefer `raspberrypi.local` (default hostname of RPi) to make CLEXI available to all devices in the network.  \nYou can change your hostname via the raspi-config tool.  \n  \nOptional: Generate some self-signed SSL certificates for your CLEXI server:  \n```\nbash generate_ssl_cert.sh\n```  \nThe tool will ask you for some info. By pressing RETURN you can keep most of the default values, just for `common name` choose your hostname (or 'localhost').  \nIf you use SSL make sure to set `\"ssl\": true` inside the settings.\n  \n### Configuration (settings.json)\n\nNext step is to adjust the CLEXI settings. Use a text editor of your choice, e.g. nano:\n```\nnano settings.json\n```  \nHere you can change the default port of your server and set the hostname to the SAME name you used for the SSL certificate (e.g. raspberrypi.local). This is important because you might not be able to reach the server otherwhise.  \nTo load specific extensions ajust the array: `\"xtensions\": [...]`. For example if you want to activate runtime commands and GPIO interface add:\n```\n\"xtensions\": [\n\t...\n\t\"ble-beacon-scanner\",\n\t\"runtime-commands\",\n\t\"gpio-interface\"\n]\n```\n\n### Run the server\n\nNow you can run your server :-)  \n```\nsudo node server.js\n```  \nYou should see a confirmation that the server is running and that extensions have been loaded (and hopefully no error ^^).  \nThe `sudo` command is required for Bluetooth control. If you want to run the server without sudo you have to grant node cap_net_raw privileges:  \n```\nsudo setcap cap_net_raw+eip $(eval readlink -f `which node`)\n```  \nFinally to check if everything worked out fine visit the test-page in your browser, e.g. `https://raspberrypi.local:8443/index.html` (depending on your settings). When using a self-signed SSL certificate this also helps to tell the browser to trust them (usually required once).\n  \n## Client installation\n\n### Clexi.js for browsers\n\nCopy latest Clexi.js library from this repository and include it in your page head, e.g.:\n```\n\u003cscript type=\"text/javascript\" src=\"lib/clexi-0.9.0.js\" charset=\"UTF-8\"\u003e\u003c/script\u003e\n```\nMake sure your server is running and reachable, then connect like this:\n```\nvar hostURL = \"wss://raspberrypi.local:8443\";\nClexiJS.serverId = 'my-clexi-server-123'; \t//must be empty or identical to 'id' entry in server settings\n  \nClexiJS.subscribeTo('ble-beacon-scanner', function(e){\n\tconsole.log('BLE Beacon event: ' + JSON.stringify(e));\n}, function(e){\n\tconsole.log('BLE Beacon response: ' + JSON.stringify(e));\n}, function(e){\n\tconsole.log('BLE Beacon error: ' + JSON.stringify(e));\n});\n  \nClexiJS.pingAndConnect(hostURL, function(err){\n\tconsole.log('server ping failed', err.msg);\n}, function(e){\n\tconsole.log('connected');\t\n}, function(e){\n\tconsole.log('closed');\n}, function(err){\n\tconsole.log('error', err.message);\n}, function(){\n\tconsole.log('connecting');\n}, function(welcomeInfo){\n\tconsole.log('welcome');\n\t\n\t//start BLE beacon scanner\n\tClexiJS.send('ble-beacon-scanner', {\n\t\tctrl: \"start\"\n\t});\n});\n```\n  \nFor more [examples](www/index.html) check the `www` folder of this repository.\n\n## Using the 'clexi-http-events' extension\n\nThis extension receives events at the 'event' endpoint and broadcasts them via the Websocket connection. The 'event' endpoint accepts HTTP GET and POST requests in the following format (curl example):\n```\n#POST example\ncurl -X POST \\\n  https://raspberrypi.local:8443/event/myEventName \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n\t\"answer\": \"42\"\n}'\n#GET example\ncurl -X GET \\\n  'https://raspberrypi.local:8443/event/myEventName?answer=42'\n```\nCLEXI will then broadcast the data as following message object to all Websocket clients:\n```\n{\"name\":\"myEventName\",\"data\":{\"answer\":\"42\"}}\n```\n\n## Adding your own extensions\n\n* Check the `xtensions` folder for references (it's pretty simple ;-))\n* Build your own extension and put the file in the same folder\n* Open `settings.json` and add your file to the xtensions array by using the filename without ending, e.g.: my-extension.js -\u003e my-extension\n* Subscribe inside your client app to your extension using the same name\n* Done :-)\n\n## Version history\n\nSee [changelog](CHANGELOG.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbytemind-de%2Fnodejs-client-extension-interface","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbytemind-de%2Fnodejs-client-extension-interface","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbytemind-de%2Fnodejs-client-extension-interface/lists"}