{"id":19134311,"url":"https://github.com/um-arm-lab/husky_ark_armlab","last_synced_at":"2025-07-17T03:34:46.477Z","repository":{"id":79650883,"uuid":"362228202","full_name":"UM-ARM-Lab/husky_ark_armlab","owner":"UM-ARM-Lab","description":"A Python ROS package to provide additional functionality for the Clearpath Autonomous Research Kit. This project was conducted for the University of Michigan's ARM Lab.","archived":false,"fork":false,"pushed_at":"2021-06-11T00:27:12.000Z","size":828,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-02-22T17:47:43.078Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://husky-ark-armlab.readthedocs.io/en/latest/","language":"Python","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/UM-ARM-Lab.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.rst","contributing":"CONTRIBUTING.rst","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.rst","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-04-27T19:29:24.000Z","updated_at":"2024-08-11T00:39:01.000Z","dependencies_parsed_at":"2023-05-14T09:00:27.778Z","dependency_job_id":null,"html_url":"https://github.com/UM-ARM-Lab/husky_ark_armlab","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/UM-ARM-Lab/husky_ark_armlab","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UM-ARM-Lab%2Fhusky_ark_armlab","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UM-ARM-Lab%2Fhusky_ark_armlab/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UM-ARM-Lab%2Fhusky_ark_armlab/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UM-ARM-Lab%2Fhusky_ark_armlab/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/UM-ARM-Lab","download_url":"https://codeload.github.com/UM-ARM-Lab/husky_ark_armlab/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UM-ARM-Lab%2Fhusky_ark_armlab/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265563076,"owners_count":23788642,"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-09T06:26:11.777Z","updated_at":"2025-07-17T03:34:46.415Z","avatar_url":"https://github.com/UM-ARM-Lab.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"================\nhusky_ark_armlab\n================\n\nThis package is meant to be used with the Clearpath Autonomous Research Kit (ARK) and provides\nadditional autonomy functionality not provided by the ARK. Although the ARK GUI has map, waypoint,\nand route creation, it only supports this for a single map. The GUI does not support switching maps,\nand all route data is erased for a previous map when a new map is created. To use routes that used\nmultiple maps, I created this ROS package to interact with the ARK's ROS API.\n\nTo see a video of this package being used to navigate autonomously between buildings,\nplease see `here \u003chttps://youtu.be/lnkzHA6yzoc\u003e`_.\n\n.. raw:: html\n\n    \u003cdiv style=\"position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden; max-width: 100%; height: auto;\"\u003e\n        \u003ciframe src=\"https://www.youtube.com/embed/lnkzHA6yzoc\" frameborder=\"0\" allowfullscreen style=\"position: absolute; top: 0; left: 0; width: 100%; height: 100%;\"\u003e\u003c/iframe\u003e\n    \u003c/div\u003e\n\n|\n\nInstallation\n------------\nYou should have already have setup the ARK (or more likely Clearpath has\nset it up for you). If this is not the case, see the documentation on installing the ARK.\n\nTo install the husky_ark_armlab package, you should first source the workspace\nyou installed the ARK in and then you should create a new workspace. Ex::\n\n    source ~/ark_ws/devel/setup.bash\n    mkdir -p ~/catkin_ws/src\n    mkdir ~/catkin_ws/\n    catkin init\n\nYou can then install the husky_ark_armlab package and dependencies::\n\n    cd ~/catkin_ws/src/\n    git clone https://github.com/UM-ARM-Lab/husky_ark_armlab.git husky_ark_armlab\n    git clone --single-branch --branch kinetic-devel https://github.com/ros-perception/laser_filters.git\n    cd ~/catkin_ws\n    rosdep install --from-paths . --ignore-src\n    catkin build\n\nYou should now source your workspace and you should be ready to run the package::\n\n    source ~/catkin_ws/devel/setup.bash\n\nRoutes\n------\nRoutes are defined through a JSON file that defines a list of maps and which map to start on.\nEach map contains a list of waypoints and which map to switch to upon completion. An example\nof a JSON route is shown below::\n\n    {\n        \"start_map\": \"top-floor-robotics\",\n        \"maps\": {\n            \"top-floor-robotics\": {\n                \"description\": \"...\",\n                \"next_map\": \"bottom-floor\",\n                \"route\": [\n                    {\n                        \"name\": \"origin\",\n                        \"description\": \"...\",\n                        \"x\": -0.121,\n                        \"y\": -0.001,\n                        \"euler_angle\": 177\n                    },\n                    {\n                        \"name\": \"outside-lab-balcony\",\n                        \"description\": \"...\",\n                        \"x\": 2.029,\n                        \"y\": -7.975,\n                        \"euler_angle\": 355\n                    },\n                ]\n            }\n        }\n    }\n\nWaypoints are specified using X, Y, and rotation with respect to the z-axis. It is not necessary to specify the Z position\nbecause the ARK only supports 2D mapping.\n\nYou can use the ARK GUI to find the XY, theta positions of the different waypoints.\nAfter creating the waypoints, you can go into \"Drive\" mode and select waypoints to\nnavigate to. When you select a waypoint, its position and orientation will be displayed.\n\nRoute Tools\n-----------\nTo speed up route creation, the package contains scripts to reverse an existing route,\nvalidate a route, and simulate a route by printing out the order that waypoints will\nbe visited.\n\nReversing a route is useful because the route only needed to be specified in\none direction, and the return route would be automatically generated (including rotating\nposes by 180 degrees, reversing waypoint order, and reversing the order of maps). You can do this with::\n\n    python src/husky_ark_armlab reverse_route.py -r ./config/initial-route.json -o ./config/reversed-route.json\n\nValidating a route is useful to ensure that any changes to the route were valid and catch issues with\nthe route before navigation began. You can do this with::\n\n    python src/husky_ark_armlab route_loader.py -r ./config/myroute.json -v\n\nSimulating a route was useful for debugging without requiring the robot to be running or using\na ROS environment. This can be done with::\n\n    python src/husky_ark_armlab simulate_route -r ./config/myroute.json\n\nKeyboard Commands\n-----------------\nWhile running the husky_ark_armlab ROS node, you can use multiple keyboard commands to interact\nwith the node. All commands should be typed in the same terminal that the node is running in.\n\n- Pause/resume autonomoy: press \u003cspace\u003e\n- Skip a waypoint: press \"n\"\n- Increase the max lidar threshold: press \"w\"\n- Shrink the max lidar threshold: press \"s\"\n- Set the max lidar threshold to a specific value: press any digit between 0-9\n\nMulti-Map Navigation\n--------------------\nTo support reduce the accumulated drift over time and make maps easier to update, you should\nbreak your route into multiple smaller maps. Each map's final waypoint\nshould correspond to the first waypoint in the following map. This allows chaining together\nmultiple maps.\n\nTo make sure the ARK accurately localizes when starting a new map, the husky_ark_armlab node will\nprovide the ARK with a starting pose, which is the first waypoint defined in a map.\n\nMultiple maps can be used to support navigation between floors of a building. The ARK\n(and most navigation packages) only supports 2D navigation. This means a map can not have multiple\nfloors. To solve this, you should include an elevator in the map for a floor.\n\nThe Husky should either began a map or end a map inside an elevator (when using an elevator).\nThis allowed us to switch maps inside an elevator when the doors were closed. The Husky can then\nre-localize with respect to the new map once the next floor was reached and the elevator doors opened.\nWhen creating maps, you should erase elevator doors to allow the Husky to treat them as only a\ntemporary obstacle. The Husky will wait outside the elevator until the doors opened, and then it\nwill proceed inside.\n\nWhen choosing the location to switch maps (for start/end positions that weren't inside elevators),\nyou should choose a location where the Husky can localize well and can easily tell which direction\nit is facing (ex. switching maps between a set of double doors is not recommended because the ARK\nwill not be able to tell which direction it is facing).\n\nAdjustable Lidar Thresholds\n---------------------------\nA major issue I faced during autonomous navigation was dealing with the sloped ground.\nThe ARK would recognize sloped ground as an obstacle (as shown below). This made it very difficult\nto path plan up or down a sloped path.\n\n.. figure:: https://github.com/UM-ARM-Lab/husky_ark_armlab/blob/master/docs/_static/lidar-sloped-ground-figure.png?raw=true\n      :alt: lidar-sloped-ground-figure\n      :class: with-shadow\n      :width: 400px\n\n      When trying to navigate up or down a sloped path, the ground ahead appears as an obstacle. The Husky is represented as a grey box, the hill as the curved black line, and the lidar scan as the red arrow.\n\nTo solve this, you can manually (see keyboard commands) adjust the max lidar thresholds during navigation or set per-waypoint\nand per-map thresholds through the route JSON configuration. Reducing the radius of the laser scans avoids detecting sloped\nground as obstacles.\n\nBecause the laser_filters package doesn't support dynamically changing thresholds for a range filter, you\nshould use the `fork I have created \u003chttps://github.com/EricWiener/laser_filters\u003e`_.\n\nConfig files\n------------\n\n-  **default.yaml** This specifies the default route to use\n-  **laser_filter_config.yaml** This configures the laser filter\n-  **robotics-to-wilson.json** Example route JSON\n-  **wilson-to-robotics.json** Example of automatically reversed route\n\nLaunch files\n------------\n\n-  **husky_ark_armlab.launch:** this will launch autonomous navigation\n   using a specified route\n\n   Required Arguments\n\n   -  **route** The absolute path to the route JSON file to use\n\n   Optional Arguments\n\n   -  **map** The map to start navigation from. This is useful for debugging.\n   -  **waypoint** The waypoint number to start navigating from\n      (zero-indexed)\n\nUsage\n-----\n\nRun the main node with\n\n::\n\n    roslaunch husky_ark_armlab husky_ark_armlab.launch route:=\u003cabsolute path to route\u003e\n\nFor example::\n\n    roslaunch husky_ark_armlab husky_ark_armlab.launch route:=/home/eric/catkin_ws/src/husky-ark/config/robotics-to-wilson.json\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fum-arm-lab%2Fhusky_ark_armlab","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fum-arm-lab%2Fhusky_ark_armlab","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fum-arm-lab%2Fhusky_ark_armlab/lists"}