diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f0298377..9c531251 100755 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,14 +9,6 @@ an issue or you want to add an enhancement. When creating a new pull request please add the issue number. -## Adding new robot -Adding new embodiment is very straightforward: -1. Create a folder with a new robot [here](https://github.com/kscalelabs/sim/tree/master/sim). -2. Add joint.py file setting up basic properties and join configuration - see an [example](https://github.com/kscalelabs/sim/blob/master/sim/resources/stompymini/joints.py). -3. Add the new embodiment configuration and environment [here](https://github.com/kscalelabs/sim/tree/master/sim/envs). -4. Add the new embodiment to the [registry](https://github.com/kscalelabs/sim/blob/master/sim/envs/__init__.py). - -We set up the logic so that your new robot should start to walk with basic configuration. ## Lint and formatting When you submit the PR we automatically run some checks using black, ruff and mypy. @@ -26,3 +18,42 @@ You can locally run commands below to test the formatting: make format make static-checks ``` + +## Adding a new robot +Creating a new embodiment is quite straightforward. The best way is to copy an existing robot and modify it. +The best starting point would be [stompymini](https://github.com/kscalelabs/sim/tree/master/sim/resources/stompymini). +1. Create a folder with a new robot [here](https://github.com/kscalelabs/sim/tree/master/sim/resources). +2. Add `joint.py` file setting up basic properties and joint configuration - see an [example](https://github.com/kscalelabs/sim/blob/master/sim/resources/stompymini/joints.py). +3. Update [height](https://github.com/kscalelabs/sim/blob/aa97ddfddcaadcac64d4f83d986548cc7fc451a6/sim/resources/stompymini/joints.py#L102) and default rotation of your humanoid. +4. Add a new embodiment configuration and environment [here](https://github.com/kscalelabs/sim/tree/master/sim/envs/humanoids). +5. Add a new embodiment to the [registry](https://github.com/kscalelabs/sim/blob/master/sim/envs/__init__.py). +To run things export your default path: +``` +export MODEL_DIR=sim/resources/NEW_HUMANOID +``` +and kick off the training: +``` +python sim/train.py --env-id NEW_HUMANOID --num-envs 4 +``` + +## Making it stand +1. The best way to start is to make your new robot stand. In this case you want to comment out +the rewards that are responsible for making the robot walk. See an example of a [reward config](https://github.com/kscalelabs/sim/blob/aa97ddfddcaadcac64d4f83d986548cc7fc451a6/sim/envs/humanoids/stompymini_config.py#L163). +2. If the robot flies away, inspect your joint limits. During training, we introduce a lot of noise to the default joint positions +as well as masses. You might need either adapt the limits or the [noise level](https://github.com/kscalelabs/sim/blob/aa97ddfddcaadcac64d4f83d986548cc7fc451a6/sim/envs/humanoids/stompy_config.py#L213). +3. Isaac Sim often hits velocities nans when some joints are hitting their limits - you can change the [engine parameters](https://github.com/kscalelabs/sim/blob/aa97ddfddcaadcac64d4f83d986548cc7fc451a6/sim/envs/humanoids/stompy_config.py#L108) to fix this issue. +4. The revolute joints cannot have 0 velocity in the URDF definition - otherwise, engine will go nans as well. +5. Observe the reward for orientation and default joint position. The model should just farm these two rewards. +6. If the robot still struggles at keeping the standing pose, you can also change the urdf definition using the [script](https://github.com/kscalelabs/sim/blob/master/sim/scripts/create_fixed_torso.py) to fix the upper body or change joint limits. + +## Making it walk +We set up the logic so that your new robot should start to walk with basic configuration after some modifications. +1. To get things going it's best to start from the good standing pose, with knees slightly bent. +See an example [Stompy's pose](https://github.com/kscalelabs/sim/blob/aa97ddfddcaadcac64d4f83d986548cc7fc451a6/sim/resources/stompymini/joints.py#L113). +2. The [gait reward](https://github.com/kscalelabs/sim/blob/aa97ddfddcaadcac64d4f83d986548cc7fc451a6/sim/envs/humanoids/stompy_config.py#L146) is the most crucial single reward. You have to adapt the hyperparameters to your robot design to get it to work. +3. If the robots tends to jump, use only one limb you will have to adapt the overall rewards schema to enforce proper behavior. +4. If the setup is correct, you should see positive results after first 200-300 epochs. However, the robust policy will requires 2000-3000 epochs. + + + + diff --git a/sim/scripts/download_assets.sh b/sim/scripts/download_assets.sh index a0d2cac4..478615db 100755 --- a/sim/scripts/download_assets.sh +++ b/sim/scripts/download_assets.sh @@ -1,7 +1,7 @@ #!/bin/zsh # Stompymini -gdown --id 19T7mY604P6hSctFymxuHbwqKQOzOtloH +gdown --id 1Ah92CTN63M2h4uKPLf8eXkX2H9Bg3Kji tar -xzvf meshes.zip -C sim/resources/stompymini/ rm meshes.zip