From 1836a0b25fcd6f2f8cebb243bdce2804566ed560 Mon Sep 17 00:00:00 2001
From: Michael Carroll <michael@openrobotics.org>
Date: Tue, 25 Oct 2022 12:06:56 -0700
Subject: [PATCH] Add top-level bullet-featherstone README (#443)

Signed-off-by: Michael Carroll <michael@openrobotics.org>
---
 README.md                     |  1 +
 bullet-featherstone/README.md | 97 +++++++++++++++++++++++++++++++++++
 2 files changed, 98 insertions(+)
 create mode 100644 bullet-featherstone/README.md

diff --git a/README.md b/README.md
index 5d9e24a7d..a3776fecb 100644
--- a/README.md
+++ b/README.md
@@ -130,6 +130,7 @@ Refer to the following table for information about important directories and fil
 ```
 gz-physics
 ├── bullet                    Files for bullet plugin component.
+├── bullet-featherstone       Files for bullet-featherstone plugin component.
 ├── dartsim                   Files for dartsim plugin component.
 ├── example                   Examples about how to use the library
 ├── heightmap                 Heightmap related header files.
diff --git a/bullet-featherstone/README.md b/bullet-featherstone/README.md
new file mode 100644
index 000000000..5444cd089
--- /dev/null
+++ b/bullet-featherstone/README.md
@@ -0,0 +1,97 @@
+# Bullet Featherstone Physics Plugin
+
+This component enables the use of this [Bullet Physics](https://github.com/bulletphysics/bullet3) `btMultiBody` Featherstone implementation.
+The Featherstone uses minimal coordinates to represent articulated bodies and efficiently simulate them.
+ 
+# Features
+
+Originally tracked via: [Bullet featherstone meta-ticket](https://github.com/gazebosim/gz-physics/issues/423)
+
+## High-level feature list
+
+* Constructing SDF Models
+* Constructing SDF Worlds
+* Joint Types: 
+  * Fixed
+  * Prismatic
+  * Revolute
+  * Ball Joint
+* Stepping the simulation world
+* Applying external forces/torques
+* Free Groups
+* Contact sensor
+
+## Physics features list
+
+These are the specific physics API features implemented.
+
+* Entity Management Features 
+  * ConstructEmptyWorldFeature
+  * GetEngineInfo
+  * GetJointFromModel
+  * GetLinkFromModel
+  * GetModelFromWorld
+  * GetShapeFromLink
+  * GetWorldFromEngine
+  * RemoveModelFromWorld
+* FreeGroupFeatures
+  * FindFreeGroupFeature
+  * SetFreeGroupWorldPose
+  * SetFreeGroupWorldVelocity
+* Kinematics Features
+  * LinkFrameSemantics
+  * ModelFrameSemantics
+  * FreeGroupFrameSemantics
+* Joint Features
+  * GetBasicJointState
+  * SetBasicJointState
+  * GetBasicJointProperties
+  * SetJointVelocityCommandFeature
+  * SetJointTransformFromParentFeature
+  * AttachFixedJointFeature
+  * DetachJointFeature
+  * GetRevoluteJointProperties
+  * GetPrismaticJointProperties
+  * FixedJointCast
+* Link Features
+  * AddLinkExternalForceTorque
+* Sdf Features
+  * sdf::ConstructSDFModel
+  * sdf::ConstructSDFWorld
+  * sdf::ConstructSDFCollision
+* Shapes Features
+  * GetShapeBoundingBox
+  * GetBoxShapeProperties
+  * AttachBoxShapeFeature
+  * GetCapsuleShapeProperties
+  * AttachCapsuleShapeFeature
+  * GetCylinderShapeProperties
+  * AttachCylinderShapeFeature
+  * GetEllipsoidShapeProperties
+  * AttachEllipsoidShapeFeature
+  * GetSphereShapeProperties
+  * AttachSphereShapeFeature
+* Simulation Features
+  * ForwardStep
+  * GetContactsFromLastStepFeature
+* World Features
+  * Gravity
+
+# Caveats
+
+* All links _must_ have a collision element.
+
+In order for links to be active, bullet checks for the presence of collision elements.
+In the case that collisions aren't available, adding a small sphere at the link origin is sufficient (but won't get good collision behavior)
+
+* All links/joints of a model must be constructed with the model
+
+Additional links/joints cannot be added to a model after initial construction.
+
+* Ellipse axis-aligned bounding box returns invalid values on Ubuntu Focal
+
+Tracked via: https://github.com/gazebosim/gz-physics/issues/440
+
+* Joint transmitted wrench doesn't accurately report forces/torques
+
+Tracked via: https://github.com/gazebosim/gz-physics/pull/434