Merge pull request jsk-ros-pkg#565 from Li-Jinjie/only_add_docs

[Docs] Only add docs

.github/workflows/uml.yml

@@ -0,0 +1,19 @@
+name: generate plantuml
+on: push
+jobs:
+  generate_plantuml:
+    runs-on: ubuntu-latest
+    name: plantuml
+    steps:
+      - name: checkout
+        uses: actions/checkout@v1
+        with:
+          fetch-depth: 1
+      - name: plantuml
+        id: plantuml
+        uses: grassedge/[email protected]
+        with:
+          path: docs/UMLs
+          message: "Render PlantUML files"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -6,7 +6,8 @@
 .LSOverride
 
 # Icon must end with two \r
-Icon
+Icon
+
 
 # Thumbnails
 ._*
@@ -101,4 +102,8 @@ tags
 
 
 # python
-*.pyc
+*.pyc
+
+# Jetbrains
+.idea/
+*cmake-build-debug/

README.md

@@ -22,5 +22,3 @@ catkin build
 
 ## Demo
 Please check instruction in [wiki](https://github.com/JSKAerialRobot/aerial_robot/wiki).
-
-

docs/UMLs/classes.puml

@@ -0,0 +1,102 @@
+@startuml
+'https://plantuml.com/class-diagram
+
+set namespaceSeparator ::
+
+abstract class aerial_robot_control::ControlBase {
+    + ControlBase()
+    + ~ControlBase()
+    + initialize()
+    + update()
+    + activate()
+    + reset()
+}
+
+abstract class aerial_robot_control::PoseLinearController extends aerial_robot_control::ControlBase {
+    + PoseLinearController()
+    + ~PoseLinearController()
+    + initialize()
+    + update()
+    + reset()
+}
+
+class aerial_robot_control::FullyActuatedController extends aerial_robot_control::PoseLinearController {
+    + FullyActuatedController()
+    + ~FullyActuatedController()
+    + initialize()
+    + reset()
+    + controlCore()
+    + sendCmd()
+}
+
+class aerial_robot_control::UnderActuatedController extends aerial_robot_control::PoseLinearController {
+    + UnderActuatedController()
+    + ~UnderActuatedController()
+    + initialize()
+    + reset()
+}
+
+class aerial_robot_control::UnderActuatedLQIController extends aerial_robot_control::PoseLinearController {
+    + UnderActuatedLQIController()
+    + ~UnderActuatedLQIController()
+    + initialize()
+    + activate()
+}
+
+class aerial_robot_control::UnderActuatedTiltedLQIController extends aerial_robot_control::UnderActuatedLQIController {
+    + UnderActuatedTiltedLQIController()
+    + ~UnderActuatedTiltedLQIController()
+    + initialize()
+    + activate()
+}
+
+class aerial_robot_control::HydrusLQIController extends aerial_robot_control::UnderActuatedLQIController {
+    + HydrusLQIController()
+    + initialize()
+    + checkRobotModel()
+}
+
+class aerial_robot_control::HydrusTiltedLQIController extends aerial_robot_control::UnderActuatedTiltedLQIController {
+    + HydrusTiltedLQIController()
+    + initialize()
+    + checkRobotModel()
+}
+
+class aerial_robot_control::DragonLQIGimbalController extends aerial_robot_control::HydrusLQIController {
+    + DragonLQIGimbalController()
+    + ~DragonLQIGimbalController()
+    + initialize()
+    + update()
+    + reset()
+}
+
+class aerial_robot_control::DragonFullVectoringController extends aerial_robot_control::PoseLinearController {
+    + DragonFullVectoringController()
+    + ~DragonFullVectoringController()
+    + initialize()
+}
+
+namespace aerial_robot_control {
+    note "under-actuated multi-rotor (quad-rotor)" as ud_mr
+    note "hydrus (option)" as hy
+    note "fully-actuated multi-rotor (tilted hex-rotor)" as fu_mr
+    note "hydrus_xi (hex type)" as hy_xi
+    note "hydrus (non tilted)" as hy_nt
+    note "dragon" as dragon
+    note "hydrus (non tilted/ tilted)" as hy_all
+}
+UnderActuatedController .. ud_mr
+UnderActuatedController .. hy
+FullyActuatedController .. fu_mr
+FullyActuatedController .. hy_xi
+HydrusLQIController .. hy_nt
+HydrusLQIController .. ud_mr
+HydrusTiltedLQIController .. hy_all
+DragonLQIGimbalController .. dragon
+DragonFullVectoringController .. dragon
+
+
+
+'TODO: give a unique namespace to robot specific controllers
+
+@enduml

docs/UMLs/folder_structure.puml

@@ -0,0 +1,123 @@
+@startuml
+'https://plantuml.com/component-diagram
+
+'Legend
+' - Blue: common packages
+' - Orange: only for simulation
+' - Green: only for real machine
+
+package "jsk_aerial_robot" {
+
+[aerial_robot_base] #LightBlue
+note right of aerial_robot_base
+  * standalone core
+  - execute functions from following blocks
+end note
+
+[aerial_robot_model] #LightBlue
+note right of [aerial_robot_model]
+  * joint based modelling
+  - kinematics, statics, stability
+  - jacobian
+  - derive model class as ros plugin
+  - servo motor interface (bridge)
+end note
+
+[aerial_robot_estimation] #LightBlue
+note right of [aerial_robot_estimation]
+  * sensor fusion
+  - cog motion estimation
+  - sensor interface as ros plugin
+  - kalman filter as ros plugin
+end note
+
+[aerial_robot_control] #LightBlue
+note right of [aerial_robot_control]
+  * flight control / navigation
+  - control based on cog motion
+  - navigation for cog and joint motion
+  - derive control/navigation class as ros plugin
+end note
+
+[aerial_robot_msgs] #LightBlue
+note right of [aerial_robot_msgs]
+  * ros messages
+  - aerial_robot_msgs/XXXXX
+end note
+
+[aerial_robot_base] -[hidden]-> [aerial_robot_model]
+[aerial_robot_model] -[hidden]-> [aerial_robot_estimation]
+[aerial_robot_estimation] -[hidden]-> [aerial_robot_control]
+[aerial_robot_control] -[hidden]-> [aerial_robot_msgs]
+
+package "robots" {
+
+  note right of "robots"
+    * derive class as plugin for:
+    - model  from aerial_robot_model
+    - control  from aerial_robot_control
+    - navigation  from aerial_robot_control (option)
+  end note
+
+  [hydrus] #LightBlue
+  note right of [hydrus]
+    - two dimensional multilinked type
+    - vertical thrust
+  end note
+
+  [hydrus_xi] #LightBlue
+  note right of [hydrus_xi]
+    - two dimensional multilinked type
+    - 1D vectorable thrust
+  end note
+
+  [dragon] #LightBlue
+  note right of [dragon]
+    - three dimensional multilinked type
+    - 2D vectorable thrust
+  end note
+
+  [hydrus] -[hidden]-> [hydrus_xi]
+  [hydrus_xi] -[hidden]-> [dragon]
+}
+
+[aerial_robot_simulation] #Orange
+note right of [aerial_robot_simulation]
+  * interface for gazebo
+  - hardware interface
+  - controller interface as plugin
+end note
+
+[aerial_robot_msgs] -[hidden]-> [aerial_robot_simulation]
+
+
+package "aerial_robot_nerve" {
+  [spinal_ros_bridge] #LightGreen
+  note right of [spinal_ros_bridge]
+    * uart between ros and spinal
+    - rosserial based
+  end note
+
+  [spinal] #LightGreen
+  note right of [spinal]
+    * project for stm32 mcu
+    - attitude estimation
+    - attitude control
+    - CAN comm with neuron
+  end note
+
+  [neuron] #LightGreen
+  note right of [neuron]
+    * project for stm32 mcu
+    - sensor interface via GPIO
+    - actuator interface via GPIO
+    - CAN comm with spinal
+  end note
+
+  [spinal_ros_bridge] -[hidden]-> [spinal]
+    [spinal] -[hidden]-> [neuron]
+}
+
+}
+
+@enduml

docs/UMLs/system_config.puml

@@ -0,0 +1,74 @@
+@startuml
+'https://plantuml.com/component-diagram
+
+
+package "Class Member as Plugins" {
+  [robot_model_loader_("aerial_robot_model",\n "aerial_robot_model::RobotModel")] as model_plugin
+  [pluginlib::ClassLoader(aerial_robot_estimation",\n "sensor_plugin::SensorBase")] as sensor_plugin
+  [pluginlib::ClassLoader("kalman_filter",\n "kf_plugin::KalmanFilter"))] as kf_plugin
+  model_plugin -[hidden]-> sensor_plugin
+  sensor_plugin -[hidden]-> kf_plugin
+}
+
+package "Load as Plugin" {
+  [navigator_loader_("aerial_robot_control",\n "aerial_robot_navigation::BaseNavigator")] as navigator_plugin
+  [controller_loader_("aerial_robot_control",\n "aerial_robot_control::ControlBase")] as controller_plugin
+  navigator_plugin -[hidden]-> controller_plugin
+}
+
+component "aerial_robot_base" as base {
+  [ROS spinal (ros::AsyncSpinner)\n4 multi-thread to call callbacks] as ROS_Spinal
+  [*Timer Loop\lVoid mainFunc(const ros::TimerEvent & e)\l{\l        navigator_->update();\l        controller_->update();\l }] as TimerLoop
+  package Instance {
+    [robot_model_ros_]
+    [estimator_]
+    [navigator_]
+    [controller_]
+  }
+}
+
+[servo_bridge]
+
+package "Simulation (Gazebo)" {
+  ["Hardware interface"]
+  ["Controller interfaces"]
+  ["Hardware interface"] -[hidden]-> ["Controller interfaces"]
+}
+
+package "Real Machine" {
+  [spinal_ros_bridge]
+  [sensor interfaces]
+  [spinal]
+}
+
+'Relationship
+
+model_plugin -> robot_model_ros_
+sensor_plugin -> estimator_
+kf_plugin -> estimator_
+
+navigator_plugin -> navigator_
+controller_plugin -> controller_
+
+robot_model_ros_ --> estimator_
+robot_model_ros_ --> navigator_
+robot_model_ros_ --> controller_
+estimator_ --> navigator_
+estimator_ --> controller_
+navigator_ --> controller_
+
+navigator_ -> TimerLoop
+controller_ -> TimerLoop
+
+Instance --> ROS_Spinal
+
+base <--> servo_bridge
+base <--> spinal_ros_bridge
+servo_bridge <--> spinal_ros_bridge
+servo_bridge <--> "Simulation (Gazebo)"
+spinal_ros_bridge <--> spinal
+[sensor interfaces] --> base
+
+kf_plugin -[hidden]-> navigator_plugin
+
+@enduml

docs/UMLs/workflow.puml

@@ -0,0 +1,48 @@
+@startuml
+'https://plantuml.com/sequence-diagram
+
+' Legend
+' ->> means inner communication via variables
+'-> means outer communication via ROS topics
+
+'for nested boxes
+!pragma teoz true
+
+autonumber
+
+box Laptop #Khaki
+participant RViz
+participant Terminal
+end box
+
+box "Onboard PC\n(Jetson NX)" #LightGreen
+participant "Nav" as Nav
+participant "Control" as Ctl
+participant "Estimator" as Est
+end box
+
+box Gazebo (Laptop) #Aliceblue
+
+    box "     MCU\n(STM32 H7)" #LightBlue
+    participant "Spinal/Control_Spawner" as Spinal
+    end box
+
+    box Body  #LightGray
+    participant "ESC&Servo" as ESC
+    end box
+
+end box
+
+Est ->> Est: 100Hz
+
+loop 40Hz
+    Est ->> Ctl: estimator_->getState()
+end loop
+
+Nav ->> Ctl: target_pos/vel/acc
+loop 10Hz
+    Ctl -> Spinal: qd/attitude\ngeometry_msgs/Vector3Stamped
+end loop
+Spinal -> ESC: PWM
+
+@enduml