{"id":19277648,"url":"https://github.com/wolkabout/wolkgateway","last_synced_at":"2025-04-22T00:31:01.243Z","repository":{"id":33519822,"uuid":"121357889","full_name":"Wolkabout/WolkGateway","owner":"Wolkabout","description":"WolkGateway bridges communication between WolkAbout IoT platform and multiple devices connected to it","archived":false,"fork":false,"pushed_at":"2024-11-27T15:03:59.000Z","size":1381,"stargazers_count":12,"open_issues_count":1,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-01T17:10:26.652Z","etag":null,"topics":["client-library","fota","gateway","iot","iot-platform","wolkabout","wolkconnect"],"latest_commit_sha":null,"homepage":"","language":"C++","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/Wolkabout.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":"2018-02-13T08:34:23.000Z","updated_at":"2024-01-23T07:10:30.000Z","dependencies_parsed_at":"2024-11-09T21:17:28.266Z","dependency_job_id":null,"html_url":"https://github.com/Wolkabout/WolkGateway","commit_stats":null,"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wolkabout%2FWolkGateway","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wolkabout%2FWolkGateway/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wolkabout%2FWolkGateway/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wolkabout%2FWolkGateway/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Wolkabout","download_url":"https://codeload.github.com/Wolkabout/WolkGateway/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250157693,"owners_count":21384329,"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":["client-library","fota","gateway","iot","iot-platform","wolkabout","wolkconnect"],"created_at":"2024-11-09T21:06:33.557Z","updated_at":"2025-04-22T00:31:00.879Z","avatar_url":"https://github.com/Wolkabout.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"```\n██╗    ██╗ ██████╗ ██╗     ██╗  ██╗ ██████╗  █████╗ ████████╗███████╗██╗    ██╗ █████╗ ██╗   ██╗\n██║    ██║██╔═══██╗██║     ██║ ██╔╝██╔════╝ ██╔══██╗╚══██╔══╝██╔════╝██║    ██║██╔══██╗╚██╗ ██╔╝\n██║ █╗ ██║██║   ██║██║     █████╔╝ ██║  ███╗███████║   ██║   █████╗  ██║ █╗ ██║███████║ ╚████╔╝\n██║███╗██║██║   ██║██║     ██╔═██╗ ██║   ██║██╔══██║   ██║   ██╔══╝  ██║███╗██║██╔══██║  ╚██╔╝\n╚███╔███╔╝╚██████╔╝███████╗██║  ██╗╚██████╔╝██║  ██║   ██║   ███████╗╚███╔███╔╝██║  ██║   ██║\n ╚══╝╚══╝  ╚═════╝ ╚══════╝╚═╝  ╚═╝ ╚═════╝ ╚═╝  ╚═╝   ╚═╝   ╚══════╝ ╚══╝╚══╝ ╚═╝  ╚═╝   ╚═╝\n\n```\n----\nWolkGateway bridges communication between WolkAbout IoT platform and multiple devices connected to it.\n\nWolkGateway supports bridging of devices using following protocol(s):\n\n* WolkAbout protocol\n\nInstalling from source\n----------------------\n\nThis repository must be cloned from the command line using:\n```sh\ngit clone --recurse-submodules https://github.com/Wolkabout/WolkGateway.git\n```\n\nPrerequisite\n------\n\nFollowing tools are required in order to build WolkGateway\n\n* CMake - version 3.5 or later\n* Mosquitto MQTT broker\n* OpenSSL\n* Optional: Docker CE (For running WolkGateway inside Docker container)\n\nFormer can be installed on Debian based system from terminal by invoking:\n\n`apt-get install mosquitto cmake libssl-dev`\n\nBuilding\n------\n\nBefore proceeding with steps from this section complete steps listed in 'Prerequisite' section.\n\n1. Generate build system by invoking `./configure` from within WolkGateway base directory.\nBuild system is generated to `out` directory\n2. Change current directory to `out`. Following steps are performed from within this directory\n3. Build WolkGateway by invoking `make all -j$(nproc)`\n4. Run WolkGateway tests by invoking `make tests -j$(nproc)`, and if you want to run them again, just execute `./WolkGatewayTests`, since you don't have to compile them again.\n\nRunning\n------\n\nYou can do `sudo make install`, which installs the program on your system, adding a `systemctl` unit file\nand placing the configuration in `/etc/wolkGateway`. After that, you can use `sudo service wolk_gateway status/start/stop`,\nand skip to the next paragraph (next section is about running it manually).\n\nBefore proceeding with steps from this section complete steps listed in 'Building' section.\n\n1. Change current directory to `out`\n2. Open `gatewayConfiguration.json` and fill name, key and password fields with data provided by WolkAbout IoT platform after gateway device creation and choose who will be responsible for registering and deleting devices - gateway or platform\n3. Make sure mosquitto is running by invoking `systemctl start mosquitto`\n4. Run gateway by invoking `./WolkGatewayApp gatewayConfiguration.json`\n\n**Note:** Running additional instances of WolkGateway on the same network requires having an additional mosquitto broker per gateway. Start a mosquitto daemon from the terminal with `mosquitto -p \u003cport\u003e -d`. The port entered here should also be entered into `gatewayConfiguration.json` for the matching gateway and into the configuration file of all of the gateway's modules.\n\nConnecting devices\n------\n\nDevices are connected to the gateway using modules. Module must implement communication protocol for specific device and manage\nall communication between devices and the gateway including sending device data and registering devices to WolkAbout platform.\n\nModule communicates with gateway via local mqtt broker which is run along with gateway.\n\nA single Module may handle multiple devices, and there may be multiple modules deployed.\n\n[WolkGatewayModule-Cpp](https://github.com/Wolkabout/WolkGatewayModule-Cpp) is a SDK which implements data handling and device registration with the gateway,\nand the user needs to implement communication with the devices.\n\nModule may be implemented in any desired language as a mqtt client.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"gateway_architecture.png\" title=\"Gateway architecture\"\u003e\n\u003c/p\u003e\n\n\nDeleting devices\n------\n\nIf subdevice management was set to `platform` in `gatewayConfiguration.json`, then the deletion of devices is enabled on the web application and the gateway stores no information about registered devices, it simply forwards all received data to the platform.\n\nIf subdevice management was set to `gateway` in `gatewayConfiguration.json`, then the gateway keeps track of all devices that are registered via modules. Keys of all registered devices are stored in a file `existingDevices.json` which is located in the same directory as gateway executable.\n\nTo delete device from gateway open `existingDevices.json` file and remove the line containing the key of device which should be deleted, and restart gateway.\nUpon starting the gateway will delete all registered devices whose keys no longer appear in `existingDevices.json` file.\n\nNote that the device will be registered again if the gateway receives registration request for that device from module.\n\n\nAdvanced usage\n------\n\nGateway can have its own feeds, configuration and firmware update.\n\n**Specifying gateway template**\n\n```cpp\n    std::map\u003cstd::string, std::string\u003e typeParameters;\n    typeParameters.insert(std::pair\u003cstd::string, std::string\u003e(\"subdeviceManagement\", \"GATEWAY\"));\n\n    wolkabout::DeviceTemplate gatewayTemplate(\n        {wolkabout::ConfigurationTemplate(\"Heating start hour\", \"HSH\", wolkabout::DataType::NUMERIC, \"\", \"8\", 0, 24)},\n        {wolkabout::SensorTemplate(\"Temperature\", \"T\", wolkabout::DataType::NUMERIC, \"\", -20, 70)},\n        {wolkabout::AlarmTemplate(\"Humidity alarm\", \"HH\", \"\")},\n        {wolkabout::ActuatorTemplate(\"Light switch\", \"SW\", wolkabout::DataType::BOOLEAN, \"\")},\n        \"\",\n        typeParameters,\n        {},\n        {});\n\n\n    wolkabout::GatewayDevice device(gatewayConfiguration.getKey(), gatewayConfiguration.getPassword(), gatewayTemplate);\n\n    auto builder = wolkabout::Wolk::newBuilder(device)\n    \t.gatewayHost(gatewayConfiguration.getLocalMqttUri())\n    \t.platformHost(gatewayConfiguration.getPlatformMqttUri())\n        .build();\n\n        wolk-\u003econnectService();\n```\n\n**Specifying actuation and configuration handlers/providers**\n```cpp\n\nauto builder = wolkabout::Wolk::newBuilder(device)\n\t.gatewayHost(gatewayConfiguration.getLocalMqttUri())\n\t.platformHost(gatewayConfiguration.getPlatformMqttUri())\n    .actuationHandler([](const std::string\u0026 reference, const std::string\u0026 value) -\u003e void {\n        // TODO Invoke your code which activates your actuator.\n\n        std::cout \u003c\u003c \"Actuation request received - Reference: \" \u003c\u003c reference \u003c\u003c \" value: \" \u003c\u003c value \u003c\u003c std::endl;\n    })\n    .actuatorStatusProvider([](const std::string\u0026 reference) -\u003e wolkabout::ActuatorStatus {\n        // TODO Invoke code which reads the state of the actuator.\n\n        if (reference == \"ACTUATOR_REFERENCE_ONE\") {\n            return wolkabout::ActuatorStatus(\"65\", wolkabout::ActuatorStatus::State::READY);\n        } else if (reference == \"ACTUATOR_REFERENCE_TWO\") {\n            return wolkabout::ActuatorStatus(\"false\", wolkabout::ActuatorStatus::State::READY);\n        }\n\n        return wolkabout::ActuatorStatus(\"\", wolkabout::ActuatorStatus::State::READY);\n    })\n    .configurationHandler([](const std::map\u003cstd::string, std::string\u003e\u0026 configuration) -\u003e void {\n        // TODO invoke code which sets gateway configuration\n    })\n    .configurationProvider([]() -\u003e const std::map\u003cstd::string, std::string\u003e\u0026 {\n        // TODO invoke code which reads gateway configuration\n        return std::map\u003cstd::string, std::string\u003e();\n    })\n    .build();\n\n    wolk-\u003econnectService();\n```\n\n**Publishing sensor readings**\n```cpp\nwolk-\u003eaddSensorReading(\"TEMPERATURE_REF\", 23.4);\nwolk-\u003eaddSensorReading(\"BOOL_SENSOR_REF\", true);\n```\n\n**Publishing actuator statuses**\n```cpp\nwolk-\u003epublishActuatorStatus(\"ACTUATOR_REFERENCE_ONE\");\n```\nThis will invoke the ActuationStatusProvider to read the actuator status,\nand publish actuator status.\n\n**Publish device configuration to platform**\n```cpp\nwolk-\u003epublishConfiguration();\n```\n\n**Publishing events**\n```cpp\nwolk-\u003eaddAlarm(\"ALARM_REF\", true);\n```\n\n**Data publish strategy**\n\nSensor readings, and alarms are pushed to WolkAbout IoT platform on demand by calling\n```cpp\nwolk-\u003epublish();\n```\n\nWhereas actuator statuses are published automatically by calling:\n\n```cpp\nwolk-\u003epublishActuatorStatus(\"ACTUATOR_REFERENCE_ONE\");\n```\n\n**Trust store**\n\nBy default Gateway searches for file named 'ca.crt' in the current directory.\n\nSee code snippet below on how to specify trust store for gateway.\n\n```c++\n\nwolkabout::GatewayDevice device(gatewayConfiguration.getKey(), gatewayConfiguration.getPassword(),\n                                gatewayConfiguration.getSubdeviceManagement());\n\nauto builder = wolkabout::Wolk::newBuilder(device)\n\t.gatewayHost(gatewayConfiguration.getLocalMqttUri())\n\t.platformHost(gatewayConfiguration.getPlatformMqttUri())\n\t// Specify trust store\n\t.platformTrustStore(\"path_to_trust_store\");\n    .build();\n\n    wolk-\u003econnectService();\n```\n\n**Firmware Update**\n\nWolkAbout Gateway provides mechanism for updating gateway and subdevices firmware.\n\nBy default this feature is disabled for gateway and enabled for subdevices.\nSee code snippet below on how to enable device firmware update for gateway.\n\n```c++\n\nclass CustomFirmwareInstaller: public wolkabout::FirmwareInstaller\n{\npublic:\n\tbool install(const std::string\u0026 firmwareFile) override\n\t{\n\t\t// Mock install\n\t\tstd::cout \u003c\u003c \"Updating firmware with file \" \u003c\u003c firmwareFile \u003c\u003c std::endl;\n\n\t\t// Optionally delete 'firmwareFile\n\t\treturn true;\n\t}\n};\n\nauto installer = std::make_shared\u003cCustomFirmwareInstaller\u003e();\n\nwolkabout::GatewayDevice device(gatewayConfiguration.getKey(), gatewayConfiguration.getPassword(),\n                                wolkabout::SubdeviceManagement::GATEWAY, true, true);\n\nauto builder = wolkabout::Wolk::newBuilder(device)\n\t.gatewayHost(gatewayConfiguration.getLocalMqttUri())\n\t.platformHost(gatewayConfiguration.getPlatformMqttUri())\n\t// Enable firmware update\n\t.withFirmwareUpdate(\"2.1.0\",\t\t\t\t\t\t\t\t// Current firmware version of the gateway\n\t\t\t\t\t\tinstaller,\t\t\t\t\t\t\t\t// Implementation of FirmwareInstaller, which performs installation of obtained gateway firmware\n\t\t\t\t\t\t\".\",\t\t\t\t\t\t\t\t\t// Directory where downloaded firmware files will be stored\n\t\t\t\t\t\t10 * 1024 * 1024,\t\t\t\t\t\t// Maximum acceptable size of firmware file, in bytes\n\t\t\t\t\t\t1024 * 1024,\t\t\t\t\t\t\t// Size of firmware file transfer chunk, in bytes\n\t\t\t\t\t\turlDownloader)\t\t\t\t\t\t\t// Optional implementation of UrlFileDownloader for cases when one wants to download device firmware via given URL\n    .build();\n\n    wolk-\u003econnectService();\n```\n\nFirmware update for gateway subdevices is enabled by default. To change default settings without enabling firmware update for gateway use the above api\nand pass false for firmwareUpdateEnabled in GatewayDevice.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwolkabout%2Fwolkgateway","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwolkabout%2Fwolkgateway","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwolkabout%2Fwolkgateway/lists"}