Abharris/clarify readmes (#4)

* clarify basic vs advanced usage in the documentation

* closed code snippets

* formatting <> text

* re-add contributor guidelines

* added another env parameter for running docker container locally

Co-authored-by: abharris <abharris@microsoft.com>

README.md

@@ -1,3 +1,6 @@
+# Turtlebot3 Sample
+If you are here for the Turtlebot3 Simulator for Bonsai, please see the [Turtlebot3 Bonsai README](./samples/turtlebot3_bonsai/README.md)
+
 # ROS Connector
 A python connector for integrating Bonsai with robotic simulations that use ROS as a message passing framework. Common simulators for robotics:
 
@@ -6,7 +9,7 @@ A python connector for integrating Bonsai with robotic simulations that use ROS
 * CoppeliaSim
 * Unity
 
-This connector is compatible with ROS2 and tested with Foxy Fitzroy.
+This connector is built for ROS2 Foxy Fitzroy.
 
 # Getting Started
 
@@ -26,8 +29,8 @@ We will come back to this later once the the simulator is ready to be connected
 
 A linux workspace or WLS2 is highly reccommended. 
 
-See [Setting up ROS in WLS2](https://jack-kawell.com/2020/06/12/ros-wsl2/) - DO NOT PROCEED with the ROS INSTALLTION section
-
+1. Install WLS2 (see WSL Installation at [Setting up ROS in WLS2](https://jack-kawell.com/2020/06/12/ros-wsl2/))
+1. Set up GUI forwarding (see Setting Up GUI Forwarding at [Setting up ROS in WLS2](https://jack-kawell.com/2020/06/12/ros-wsl2/))
 1. [Install ROS2 ](https://docs.ros.org/en/foxy/Installation.html)
 1. [Configure your ROS2 Environment](https://docs.ros.org/en/foxy/Tutorials/Configuring-ROS2-Environment.html)
 1. Create a workspace [Example](https://docs.ros.org/en/foxy/Tutorials/Workspace/Creating-A-Workspace.html)
@@ -96,7 +99,27 @@ Follow the instructions for [Adding a Training Simulator](https://docs.microsoft
 
 Once the simulator is available in your Bonsai workspace, you can develop an Inkling file to train a policy. A sample inkling file can be found in the turtlebot3_bonsai package's inkling folder. 
 
+## Contributing
+
+This project welcomes contributions and suggestions.  Most contributions require you to agree to a
+Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
+the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
+
+When you submit a pull request, a CLA bot will automatically determine whether you need to provide
+a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
+provided by the bot. You will only need to do this once across all repos using our CLA.
+
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
+contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
+
+## Trademarks
 
+This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft 
+trademarks or logos is subject to and must follow 
+[Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
+Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
+Any use of third-party trademarks or logos are subject to those third-party's policies.
 
 
 

samples/turtlebot3_bonsai/README.md

@@ -1,41 +1,48 @@
 # TURTLEBOT3 BONSAI
 This sample provides a Dockerfile and associated code to train reinforecment learning policies for Turtlebot3 using Microsoft Bonsai. 
 
-## Getting Started
-This sample assumes that you have access to an Azure Subscription and have set up a Bonsai workspace. See [Microsoft Account Setup](https://docs.microsoft.com/en-us/bonsai/guides/account-setup).
+# Getting Started
+This sample assumes that you have access to an Azure Subscription and have set up a Bonsai workspace. See [Microsoft Bonsai Account Setup](https://docs.microsoft.com/en-us/bonsai/guides/account-setup).
 
-You will need a Linux build environment, azure CLI, and ROS2 Foxy. 
+## Building and Running the Simulator Locally
+To run the simulator locally, you will need to install Docker on your machine. In a command line shell (ex: powershell, bash):
 
-## Build and Run Locally
-Clone this repo into the src/ directory of your ROS2 workspace with `--recurse-submodules`. Also set an environement variable with `export TURTLEBOT3_MODEL=burger`
+* navigate to the samples/ directory 
+* `docker image build -f turtlebot3_bonsai/Dockerfile . -t <image name> --build-arg WORLD=<world>`
+* copy and edit the env.example file in the config folder with your Bonsai workspace settings
+* `docker container run <image name> --env-file=turtlebot3_bonsai/config/<env file>`
 
 Note: the <world> options are 
 * warehouse
 * racetrack
 * small_house
 * bookstore
 
-These worlds refoer to OSS gazebo world models created by AWS Robotics. 
+The world determines the environment that the turtlebot3 will be launched in. They reference OSS gazebo models created by AWS Robotics. You can learn more about these worlds at 
 
-Then, navigate to the samples/ directory.
+* https://github.com/aws-robotics/aws-robomaker-small-warehouse-world
+* https://github.com/aws-robotics/aws-robomaker-racetrack-world
+* https://github.com/aws-robotics/aws-robomaker-small-house-world
+* https://github.com/aws-robotics/aws-robomaker-bookstore-world
 
-If you want to run the simulator locally:
-* `cd turtlebot3_bonsai`
-* `colcon build`
-* `source install/setup.bash`
-* `ros2 launch turtlebot3_bonsai <world>.launch.py`
+## Building and Running the Simulator in the Cloud
+To add the simulator as a managed option in your Bonsai workspace, you will need to install the azure-cli `pip install azure-cli`. 
+
+See [How to Install the Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli) if you would prefer to use a method different from pip. 
+
+In a command line shell (ex: powershell, bash):
 
-If you want to create a local docker container:
 * navigate to the samples/ directory 
-* `docker image build -f turtlebot3_bonsai/Dockerfile . -t <image name> --build-arg WORLD=<world>
+* `az login`
+* `az acr login -n <bonsai workspace name>`
+* `az acr build --image <image name> --registry <bonsai azure container registry name> --file turtlebot3_bonsai/Dockerfile . --build-arg WORLD=<world>`
+* In the Bonsai UI, go to '+ Add sim' and select 'Other'
+* Add your <image name> to the path to the ACR image and name your sim. 
+* Recommended settings - OS: Linux, Max Instance Count: 25, Cores: 2, Memory: 4GB
 
-If you want to create a docker image in your Azure Container Registry:
-* az login
-* az acr login -n <bonsai workspace name>
-* az acre build --image <image name> --registry <bonsai workspace name> --file turtlebot3_bonsai/Dockerfile . --build-arg WORLD=<world>
+You should now be able to link your brain to this simulator. Note that running this sim will significantly speed up training time at the cost of Azure spend. 
 
-## Setup Cloud Sim with Bonsai
-Follow step 2 of [Adding a Training Simulator](https://docs.microsoft.com/en-us/bonsai/guides/add-simulator?tabs=add-cli%2Ctrain-inkling&pivots=sim-platform-other) to associate this docker image with your Bonsai workspace
+Note: if you are unsure of what your Azure Container Registry name is, it is most likely the same name as your Bonsai workspace. You can also find it within a resource group in the Azure portal named `bonsai-rg-<workspace name>-<uuid>`.
 
 ## Training
 See the turtlebot3_bonsai/inkling/ directory for an example inkling file
@@ -47,9 +54,45 @@ If you want to run the brain in the simulation loop, export the brain for linux-
 
 If you want to run the brain on your turtlebot3, export the brain for linux-arm32v7 and follow the deployment instructions. Note that if you have a turtlebot3 running a pi 4, you may need to export the brain for linux-arm64v8. On the robot, run `ros2 launch turtlebot3_bringup robot.launch.py` and `ros2 launch turtlebot3_bonsai policy_without_sim.launch.py`. 
 
-## Other 
+# Advanced Usage
+If you are interested in editing the simulation or running it directly on your machine without a container, you will need a Linux build environment, the azure CLI, and ROS2 Foxy. It is highly recommended that you are familiar with developing and building ROS projects before proceeding. 
+
+## Build without Docker
+
+If you want to run the simulator locally without docker:
+* `mkdir <workspace name> && cd <workspace name>`
+* `mkdir src`
+* clone this repo into the src folder
+* `colcon build`
+* `source install/setup.bash`
+* `ros2 launch turtlebot3_bonsai <world>.launch.py`
+
+## Editing the Simulator
+
 If you wish to change the behavior of the simulation itself (such as adding a new sensor to the robot), you may need to edit some or all of the following files:
 * config/turtlebot3_sim_interface.json
 * turtlebot3_sim_connection.py
 * turtlebot3_sim_.py
-* <world>.launch.py
+* <world>.launch.py
+
+## Contributing
+
+This project welcomes contributions and suggestions.  Most contributions require you to agree to a
+Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
+the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
+
+When you submit a pull request, a CLA bot will automatically determine whether you need to provide
+a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
+provided by the bot. You will only need to do this once across all repos using our CLA.
+
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
+contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
+
+## Trademarks
+
+This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft 
+trademarks or logos is subject to and must follow 
+[Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
+Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
+Any use of third-party trademarks or logos are subject to those third-party's policies.

samples/turtlebot3_bonsai/config/env.example

@@ -0,0 +1,3 @@
+TURTLEBOT3_MODEL=burger
+SIM_WORKSPACE="YOUR_WORKSPACE_ID"
+SIM_ACCESS_KEY="YOUR_WORKSPACE_ACCESS_KEY"