{"id":20768490,"url":"https://github.com/pieye/nimbus-ros","last_synced_at":"2025-04-30T11:26:31.772Z","repository":{"id":131487763,"uuid":"221663114","full_name":"pieye/nimbus-ros","owner":"pieye","description":"ROS driver for the Nimbus 3D Lidar Camera","archived":false,"fork":false,"pushed_at":"2021-04-02T21:55:50.000Z","size":63532,"stargazers_count":9,"open_issues_count":0,"forks_count":4,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-30T15:47:03.023Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://wiki.ros.org/nimbus_3d_driver","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pieye.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","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-11-14T09:48:32.000Z","updated_at":"2024-01-23T09:41:42.000Z","dependencies_parsed_at":"2023-05-14T06:30:16.848Z","dependency_job_id":null,"html_url":"https://github.com/pieye/nimbus-ros","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/pieye%2Fnimbus-ros","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pieye%2Fnimbus-ros/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pieye%2Fnimbus-ros/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pieye%2Fnimbus-ros/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pieye","download_url":"https://codeload.github.com/pieye/nimbus-ros/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251689877,"owners_count":21627999,"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":[],"created_at":"2024-11-17T11:39:10.336Z","updated_at":"2025-04-30T11:26:31.754Z","avatar_url":"https://github.com/pieye.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"./assets/PIEYE_Logo_RGB_POS.png\" align=\"right\" title=\"pieye logo\" width=\"220\" \u003e\n\u003cimg src=\"./assets/IWT.png\" align=\"right\" title=\"pieye logo\" width=\"120\" \u003e\n\n# Nimbus 3D - ROS driver.\n\n## 0. Preparation\nA raspberry Pi4 is highly recommended, because only it has a real 1GBit/s ethernet interface, which is needed for high frame rates. In addition, the Pi4 is recommended for local image processing, since only the Pi4 has sufficient CPU resources left.\n\nIf you have ROS noetic and are just interested to get started as easy as possible to have the pointcloud in ROS, you can use the branch \"noetic-remote\". It makes use of the nimbus-server which is really easy to use but has a significant overhead in resources. \n\nThe following step (1. Installation) is only required if you want to set it up yourself.\nOtherwise use our prepared [Raspberry Pi OS (buster)](https://cloud.pieye.org/index.php/s/nimbus3D) images.\n\nFruthermore here is the official [documentation](https://nimbus-docs.readthedocs.io/en/latest/index.html).\n\n\n## 1. Installation\n\n* [Install](https://github.com/pieye/nimbus-userland) the required software packages for nimbus\n* Clone this Repository in the src folder of your ROS workspace \n``` \nmkdir -p ~/catkin_ws/src\ncd ~/catkin_ws/src\ngit clone https://github.com/pieye/nimbus-ros.git\n``` \n\nTo perform the following installation 4GB memory is required. If this is not available, the swap size must be increased accordingly:\n``` \nsudo dphys-swapfile swapoff\nsudo nano /etc/dphys-swapfile\n``` \n\nChange these lines ``` CONF_SWAPSIZE=3000``` ```CONF_MAXSWAP=4096```\n``` \ndphys-swapfile setup\nsudo dphys-swapfile swapon\n``` \n\n* [Install ROS Melodic from Source](http://wiki.ros.org/ROSberryPi/Installing%20ROS%20Melodic%20on%20the%20Raspberry%20Pi) manually OR run the following install script: \n``` \n./nimbus-ros/scripts/install.sh\n``` \n* Build `nimbus_3d_driver`\n``` \ncd ~/catkin_ws\ncatkin_make\n```\n    \n## 2. Configure [ROS to run accros multiple machines](http://wiki.ros.org/ROS/Tutorials/MultipleMachines)\n\nThe following diagram shows the possible architectures for using your Nimbus 3D. The ROS driver \"nimbus_3d_driver\" is running on the Raspberry Pi and publishes the pointcloud. In this guide the ROS master is also running  on the Pi, but it could run on any other machine in your local network. The Pointcloud is afterwards visualized on another Computer with a Display connected e.g. Laptop. Your algorithms to process the captured data can run locally on your Raspberry or any other device in the local network. \n\n\n\u003cimg src=\"./assets/nimbus_ros.png\" align=\"center\"\u003e\n\n\n* We now configure ROS to run the master on the Raspberry and access the data via another machine running ROS Melodic with RVIZ installed\n* Add this line to the .bashrc of your other machine (laptop), after adapting the IP to your Raspberry Pi if you are using Linux. You also need to add the IP of your local machine (ROS_IP):\n\n```\nnano ~/.bashrc\nexport ROS_MASTER_URI=http://192.168.1.1:11311\nexport ROS_IP=192.168.1.1\n```\nIf you are using Windows you need to set it up as an enviroment variable:\n```\nName: ROS_MASTER_URI      Value: http://192.168.1.1:11311\nName: ROS_IP      \t  Value: 192.168.1.1\n```\n* SSH into your Raspberry and run:\n```\nroscore\n```\n* Start RVIZ on your machine:\n```\nrviz\n```\nIt should start if everything works as expected.\n\nOtherwise try to add a rule to your firewall on your machine. (Change the IP accordingly)\n```\nsudo ufw allow from 192.168.1.23/24\n```\n\n\n## 3. Start the Nimbus ROS Driver\n* The given launch file starts the nimbus node and a static coordinate transform after executing it on the Raspberry.\n```\n    source devel/setup.bash \n    roslaunch nimbus_3d_driver nimbus.launch\n  ```  \n* It is possible to adjust the topics where the Pointcloud, Intensity Image, and Range Image are published. Simply set a new topic name in the launch file. This is necessary when using multiple Nimbus cameras in your local network at the same time.\n\n* Starting RVIZ on any correcly setup device with a monitor, a poincloud and two images should be visible as shwon here:\n\u003cimg src=\"./assets/nimbus_ros.gif\" align=\"center\"\u003e\n\n\n## 4. Configure the driver to your needs\nit is possible to adjust the parameters that have an impact on the amount of transmitted data.\n* A 1GBit/s ethernet connection to the Raspberry Pi is highly recommended. If this is given you can launch the default configuration without making any changes.\n* If you only have a 100MBit/s Interface you can load the given preset by changing the default.yaml to fast_ethernet.yaml in the launch file (launch/nimbus.launch). This will reduce the resolution!\n* If you need to reduce the bandwitdh even further (e.g. wifi) but still need a reliable point cloud, you can replace the config against the low_bandwitdh.yaml This will heavily reduce the resolution!\n* Furthermore it is possible to adjust the parameters to your own needs.\n\nDepending on the given setup it might be useful to adjust the auto exposure.\nIf objects are moving fast or a minimum framerate should be achieved it can help do disable hdr and set a max value for the exposure time. The desired exposure can also be adjusted.\n\nFurthermore it is possible to change the following parameters during runtime:\n```\nrosparam set \n                /nimbus_3d_driver_node/XYZ_to_m\t\t  \t  [0.0 - 1.0]\n                /nimbus_3d_driver_node/amplitude\t\t  [0 - 3000]\n                /nimbus_3d_driver_node/downsampling\t\t  [true | false]\n                /nimbus_3d_driver_node/downsampling_voxel_size    [0.0 - 1.0]\n                /nimbus_3d_driver_node/hdr_factor\t\t  [0.0 - 1.0]\n                /nimbus_3d_driver_node/exposure_mode\t\t  [-1 (manual), 0 (default), 1 (Auto), 2 (HDR)]\n                /nimbus_3d_driver_node/intensity_image\t  \t  [true | false]\n                /nimbus_3d_driver_node/max_exposure\t\t  [0 - 32766]\n                /nimbus_3d_driver_node/pointcloud\t\t  [true | false]\n                /nimbus_3d_driver_node/range_image                [true | false]\n```\n\n## 5. Clock synchronization\nEach pointcloud includes the timestamp of the initial image aquisition. If this is needed across devices, a clock synchronization protocal such as NTP should be used. PTP hardware timestamping is not available on the Raspberry Pi. [Chrony](https://www.linuxtechi.com/sync-time-in-linux-server-using-chrony) is as often used tool for that task.\n\n\n## 6. Start developing your own Software for the Nimbus 3D\nIn addition to the this ROS driver template packages for your future C++ software is included in the package \"nimbus_example_c\". You can run it by executing:\n```\nrosrun nimbus_example_c example\n```\nIt includes basic ROS functionallity to start your development.\n\n## 7. FAQ\nThere is a possibility of encountering the bellow error upon running the nimbus node.\n```\nFATAL [nimbusRaw.cpp-\u003eerrno_exit:68]\t\n\t*******\t EXIT trigger caused by LOG(FATAL) entry: \n\t\"VIDIOC_S_FMT error 16, Device or resource busy\n*******\tSTACKDUMP *******\n```\nThis error is due to nimbus camera is currently used by nimbus-server. This service automatically started during the start-up. Follow the following steps to remove this error.\n\n* Run `sudo systemctl status nimbusServer.service` to check the staute od nimbus server. \n```\n● nimbusServer.service - Nimbus streaming server\n   Loaded: loaded (/etc/systemd/system/nimbusServer.service; enabled; vendor preset: enabled)\n   Active: active (running) since Tue 2020-02-25 15:41:17 GMT; 15h ago\n Main PID: 575 (nimbusServer)\n    Tasks: 85 (limit: 4035)\n   Memory: 12.4M\n   CGroup: /system.slice/nimbusServer.service\n           └─575 /usr/local/bin/nimbusServer\n``` \n* You need to stop the active service to run ROS node. By running \n`sudo systemctl stop nimbusServer.service`\n* Before running the ROS node check the service status again to confirm  `Active: inactive (dead)`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpieye%2Fnimbus-ros","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpieye%2Fnimbus-ros","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpieye%2Fnimbus-ros/lists"}