HSM.md

-# WIP
+In **hierarchical state machines** states are organized in a hierarchy. This means that states can be other state machines.  
 
-Hierarchical State Machine
+## Implementation
+In *skyward-boardcore* implementation, the **HSM** class extends the [EventHandler](EventHandler) class, as for FSMs.  
+  
+The main difference is that we can specify super-state and perform transiotions to them.  
+  
+Moreover, state methods should return a value of type `State`:
+```cpp
+enum State
+{
+    HANDLED   = 0,
+    IGNORED   = 1,
+    TRAN      = 2,
+    SUPER     = 3,
+    UNHANDLED = 4
+};
+```
+For example:
+```cpp
+State state_myState(const Event& ev) 
+{ 
+    ...
+
+    switch(ev.sig)
+    {
+        case EV_1:
+            ...
+        case EV_2:
+            ...
+        default:
+            ...
+    }
+
+    return HANDLED;
+}
+```
+The HSM class also defines an `Hsm_top` state, which indicates the top level state in the hierarchy. We can say that states that do not belong to any other super-state, are sub-states of `Hsm_top`.
+
+#### Methods
+Available public methods are:
+- **State transition(State (T::*nextState)(const Event&))**: perform a transition from the current state to the state that is specified as a parameter.
+- **State tran_super(State (T::`*superState)(const Event&))**: perform a transition from the current state to the super-state that is specified as a parameter.
+- **bool testState(State (T::\*test_state)(const Event&))**: test is the state machines is in a specific state (that is passed as a parameter).
+
+#### Standard Events
+As for FSMs, `EV_ENTRY` and `EV_EXIT` are automatically posted when entering or exiting a state. Moreover, by handling `EV_INIT` in a suprt-state we can perform the transition to the initial sub-state.  
+  
+You can find the complete implementation of the HSM class in `src/shared/events/HSM.h`.
 
 ## Example
 This example implements the following very simple hierarchical state machine behavior:
 
 ![HSM](images/hsm/hsm.png)
 
-Whenever the state machine moves to state `S2` (super-state), it will automatically transition to its first sub-state, that is `S3`.  
+Whenever the state machine moves to state `S2` (super-state), it will automatically transition to its first sub-state, that is `S3` (`S2` is a state machine itself and `S3` is its initial state).
 We can notice that state `S3` only has a self-loop trasition that is triggered by event `EV_2`. However, if the HSM receives an event `EV_1` while being in state `S3`, the event is handled by state `S2`, which is a super-state of `S3`.  
   
 No action is specified for the involved events (`EV_ENTRY`, `EV_EXIT`, `EV_1`, `EV_2`). They simply trigger the transitions.