{"id":13691734,"url":"https://github.com/Cumulocity-IoT/cumulocity-agents-linux","last_synced_at":"2025-05-02T15:32:57.292Z","repository":{"id":41745603,"uuid":"379584187","full_name":"Cumulocity-IoT/cumulocity-agents-linux","owner":"Cumulocity-IoT","description":"Cumulocity Linux agent is a generic agent for connecting Linux-powered devices to Cumulocity's IoT platform. It runs on all major Linux distributions (Ubuntu, Debian, Raspberry Pi OS, CentOS, etc.).","archived":false,"fork":false,"pushed_at":"2024-02-06T13:02:33.000Z","size":557,"stargazers_count":1,"open_issues_count":3,"forks_count":0,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-23T13:16:22.474Z","etag":null,"topics":["agent","cumulocity-agent","cumulocity-iot","iot-analytics"],"latest_commit_sha":null,"homepage":"","language":"HTML","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/Cumulocity-IoT.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":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2021-06-23T11:46:07.000Z","updated_at":"2024-10-14T13:59:16.000Z","dependencies_parsed_at":"2024-04-08T01:59:23.733Z","dependency_job_id":"cd24e555-b91b-4280-a5f4-fd4bd25dc307","html_url":"https://github.com/Cumulocity-IoT/cumulocity-agents-linux","commit_stats":null,"previous_names":["cumulocity-iot/cumulocity-agents-linux","softwareag/cumulocity-agents-linux"],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cumulocity-IoT%2Fcumulocity-agents-linux","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cumulocity-IoT%2Fcumulocity-agents-linux/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cumulocity-IoT%2Fcumulocity-agents-linux/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cumulocity-IoT%2Fcumulocity-agents-linux/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Cumulocity-IoT","download_url":"https://codeload.github.com/Cumulocity-IoT/cumulocity-agents-linux/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252063139,"owners_count":21688655,"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":["agent","cumulocity-agent","cumulocity-iot","iot-analytics"],"created_at":"2024-08-02T17:00:49.760Z","updated_at":"2025-05-02T15:32:56.006Z","avatar_url":"https://github.com/Cumulocity-IoT.png","language":"HTML","funding_links":[],"categories":["IoT \u0026 Analytics"],"sub_categories":["![cumulocity_64x64](https://user-images.githubusercontent.com/23717841/230378694-959dcc10-00ef-4e6a-ad4b-d1a13cec5f6d.png) Cumulocity IoT"],"readme":"# Cumulocity Linux Agent #\n\nCumulocity Linux agent is a generic agent for connecting Linux-powered devices to Cumulocity's IoT platform. It runs on all major Linux distributions (Ubuntu, Debian, Raspberry Pi OS, CentOS, etc.).\n\n### Current Features ###\n\n* Periodically report memory usage to Cumulocity.\n* Periodically report system load to Cumulocity.\n* Send log files (dmesg, syslog, journald, agent log) to Cumulocity on demand.\n* Modbus-TCP and Modbus-RTU\n* CANopen (using SocketCAN interface)\n* Monitoring\n* Cloud Remote Access for remotely accessing assets via VNC/Telnet/SSH protocols\n\n### How to build the agent? ###\n\n* Prerequisites:\n    - Linux (\u003e= 2.6.32)\n\n    - liblua (\u003e= 5.1)\n\n    - libcurl (\u003e= 7.57.0)\n\n    - Systemd (optional, for automatically starting the agent on boot)\n\n    - LuaSocket (optional, only for the use of CANopen)\n\n* Build the [Cumulocity C++ library](https://bitbucket.org/m2m/cumulocity-sdk-c) with the default *Makefile* and *common.mk* as *init.mk*.\n* Download the agent source code:\n\n```bash\ngit clone git@bitbucket.org:m2m/cumulocity-agents-linux.git\n\n```\n\n* Export the Cumulocity C++ library path (add the following code to your ~/.bashrc for permanence):\n\n```bash\nexport C8Y_LIB_PATH=/library/root/path\n```\n* Copy the compiled library files to the *lib/* directory under the agent root directory.\n\n```bash\ncd cumulocity-agents-linux\ncp -rP $C8Y_LIB_PATH/lib $C8Y_LIB_PATH/bin .\n```\n\n* Build the agent:\n```bash\nmake # in *debug* mode:\n```\n\nOr\n\n```bash\nmake release # in *release* mode:\n```\n\n* Install the agent:\n```\nsudo make install\n```\n\n* Run the agent:\n\n```bash\nsudo cumulocity-agent\n```\n\nOr for Linux distributions with systemd:\n\n```bash\nsudo systemctl enable cumulocity-agent\nsudo systemctl start cumulocity-agent\n```\n\n#### How to enable Modbus support in the agent ####\nModbus support is by default disabled. To enable modbus support, you need to edit the Makefile to set`PLUGIN_MODBUS:=1`.\nThe modbus feature requires libmodbus library, make sure you have libdmobus installed before build with modbus support.\n\nAlso, add `modbus` to the following line in cumulocity-agent.conf:\n```\nlua.plugins=system,logview,shell,version,modbus\n```\n\n#### How to enable CANopen support in the agent ####\nCANopen is composed of two parts. A Lua plugin, which is included into the agent build by default. However, to actually\nget CANopen support, you would also need to build the Cumulocity CANopen service, which is a C program based on the\nCANopen library and SocketCAN connector from Port Automation.\n\nThe CANopen library and SocketCAN connector is commercially licensed by [port industrial automation GmbH](https://www.port.de/en/products/canopen/software.html), and are not included in the repo. You\nwould need to get them from Port if you want to build the Cumulocity CANopen service.\n\nAssume you have the CANopen library and SocketCAN connector available, you need to create a directory `ext/port` in the\nrepo and exatrct the zip files there. After the extracion, your `ext/port` folder should have the following strcture:\n\n```bash\n$ ls -hl ext/port/\ndrwxr-xr-x 1 tiens tiens   44 Nov 27 16:45 canopen\ndrwxr-xr-x 1 tiens tiens   80 Nov 27 16:45 drivers\n$ ls -hl ext/port/canopen\n-rw-r--r-- 1 tiens tiens 11K Nov 27 16:45 CHANGELOG\ndrwxr-xr-x 1 tiens tiens 664 Nov 27 16:45 include\ndrwxr-xr-x 1 tiens tiens 834 Nov 27 16:45 source\n$ ls -hl ext/port/drivers\n-rw-r--r-- 1 tiens tiens  21K Nov 27 16:45 CHANGELOG_DRV\ndrwxr-xr-x 1 tiens tiens   92 Nov 27 16:45 linux\n-rw-r--r-- 1 tiens tiens 7.3K Nov 27 16:45 README\ndrwxr-xr-x 1 tiens tiens  206 Nov 27 16:45 shar_inc\ndrwxr-xr-x 1 tiens tiens  106 Nov 27 16:45 shar_src\n```\n\nTo build and run the Cumulocity CANopen service:\n\n```bash\n$ cd canopen\n$ make\n$ cd ..\n$ ./bin/c8y_canopend\n```\n\nThe Cumulocity CANopen service needs NO configuration. It's communicating with the Linux Agent via UDP port 9677. It\ngets all configuration, including SocketCAN interface, baudrate etc. automatically from the Linux Agent, so you just\nneed to adjust all the CANopen settings in the Linux Agent.\n\nThere is also a CANopen simulator included in the repo for testing purpose. To build and run it:\n\n```bash\n$ cd tools/canopen_simulator\n$ make\n$ ./c8y_canopen_simulator 5 0\n```\n\nNote 5 is the CANopen Node ID that you want the simulator to run with, and 0 is the CAN interface number, i.e., can0.\nIn this example, the simulator is automatically connected to SocketCAN interface `can0`,\nmake sure that you have a proper can0 CAN interface, or use the default CANopen settings\nin the Linux Agent to have the agent creates a vcan can0 interface for you.\n\n#### How to enable the Monitoring extension ####\n\nAdd `monitoring` to the following line in cumulocity-agent.conf:\n```\nlua.plugins=system,logview,shell,version,monitoring\n```\nLuaposix library is also required:\n\n```bash\nsudo yum install luarocks\nsudo luarocks install luaposix\n```\n\n\n### FAQ ###\n\n#### How can I uninstall the agent? ####\n\nRun:\n\n```bash\nsudo make uninstall\n```\n\n#### How can I build RPM of the agent? ####\n\nAfter building of the agent run:\n\n```bash\nsudo make rpm args='-r 1.1' # replace 1.1 with required rpm release number\n```\nThe RPM is saved in folder build/rpm.\n\n#### How can I build and package the agent as a Ubuntu snap? ####\n\n  The requirements are the same as above, but the build requires special treatment because Ubuntu Snap Core uses its\n  own file system structure, instead do:\n\n```bash\nmake release  PREFIX=/snap/cumulocity-agent/current/usr DATAPATH=/var/snap/cumulocity-agent/common\nmake snap PREFIX=/snap/cumulocity-agent/current/usr DATAPATH=/var/snap/cumulocity-agent/common\n```\n\nThis will create the snap package. Then the agent needs to be installed in developer mode, since snap sandboxing is\ncurrently too restrictive. To install it run:\n\n```bash\nsudo snap install \u003cagent.snap\u003e --devmode\n```\n\nThe agent starts automatically after installation, also at every time the machine boots.\n\nNOTE: packaging requires snapcraft \u003e= 2.10 because lower versions do not support the confinement property, which is\nrequired for packaging the agent as a snap.\n\n#### How can I connect the agent through a proxy? ####\n\nOn CentOS 7 edit _cumulocity-agent.service_:\n\n```bash\nsudo vim /etc/systemd/system/cumulocity-agent.service\n```\n```\n[Unit]\nDescription=cumulocity-agent\nAfter=network.target\n\n[Service]\nType=idle\nEnvironment=http_proxy=http://\u003chost\u003e:\u003cport\u003e\nEnvironment=https_proxy=http://\u003chost\u003e:\u003cport\u003e\nExecStart=/usr/bin/srwatchdogd /usr/bin/cumulocity-agent 240\n\n[Install]\nWantedBy=multi-user.target\n```\nThen reload systemd manager configuration and restart the agent:\n```bash\nsudo systemctl daemon-reload\nsudo systemctl restart cumulocity-agent\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCumulocity-IoT%2Fcumulocity-agents-linux","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FCumulocity-IoT%2Fcumulocity-agents-linux","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCumulocity-IoT%2Fcumulocity-agents-linux/lists"}