EventBroker.md

@@ -3,7 +3,7 @@ The **EventBroker** allows to post events to specific topics, as in a [Publish-S
 The following image shows a simple scenario with two topics (`TOPIC_1` and `TOPIC_2`), two publishers (one that publishes on topic `TOPIC_1` and the other that publishes on both topics) and two subscribers (one subscribed to both topics and one subscribed only to topic `TOPIC_2`).  
 Then, `Subscriber 1` will receive events that are published both on `TOPIC_1` or on `TOPIC_2`, while `Subscriber 2` will only received the events that are posted on `TOPIC_2`.
 
-![EventBroker](images/event_broker/pubsub.png)
+<div align="center"><img src="images/event_broker/pubsub.png" height="200"/><br/><i></i></div><br>
 
 ## Implementation
 The EventBroker is a [singleton](Singleton), [active object](Active-Object).  
@@ -14,12 +14,12 @@ In order to manage this events exchange, the broker maintains a map that associa
 map<uint8_t, vector<EventHandlerBase*>> subscribers;
 ```
 
-The events that are posted to the broker are put in an event queue. The active object thread takes care of removing events from the event queue and to forward them to all the subscribers, according to the vectors stored in the `subscribers` map.
+When an event is posted to a topic, it is forwarded to all the subscribers of that topic, according to the vectors stored in the `subscribers` map.
 
 #### Methods
 In addition to the Singleton and ActiveObject methods, the EventBroker exposes:
 - **void post(const Event& ev, uint8_t topic)**: post an event to a specific topic.
-- **uint16_t postDelayed(const Event& ev, uint8_t topic)**: post an event to a specific topic after a given delay in milliseconds (the delay can be passed as a template, e.g. _postDelayed<100>(...)_).
+- **uint16_t postDelayed<>(const Event& ev, uint8_t topic)**: post an event to a specific topic after a given delay in milliseconds (the delay can be passed as a template, e.g. _postDelayed<100>(...)_).
 - **void removeDelayed(uint16_t id)**: remove a pending delayed event from the event queue.
 - **void subscribe(EventHandlerBase\* subscriber, uint8_t topic)**: subscribe the given subscriber to the specified topic.
 - **void unsubscribe(EventHandlerBase\* subscriber, uint8_t topic)**: unsubscribe the given subscriber to the specified topic. If no topic is passed, the unsubscribe the subscriber from every topic it was subscribed to.
@@ -32,7 +32,15 @@ Moreover, the EventBroker module also defines a macro that can be seen as a shor
 
 You can find the complete implementation of the EventBroker in `src/shared/events/EventBroker.h`.
 
-> :warning: **WARNING: note that the current *EventBroker* implementation does not support posting events that contain a payload. See the [events basics](Events) page to know how events are structured.**
+> :warning: **Notice that the current *EventBroker* implementation does not support posting events that contain a payload. See the [events basics](Events) page to know how events are structured.**
+
+#### Delayed Events
+
+When a **delayed event** is posted, it is put in a queue maintained by the EventBroker. The broker's active object thread takes care of removing the delayed events from the queue when their deadline is passed and to actually post them to the required topic.
+
+The reason why the _postDelayed<>()_ method is a template function is that it allows to check that the given delay is grater than a minimum value (`EVENT_BROKER_MIN_DELAY`) at compile time, using a static assert.
+
+> :information_source: **Only the _delayed events_ are managed and posted by the broker's active object thread. All the other events (_"normal" events_) are posted and forwarded to the subscribers by the caller thread (i.e. the one that is publishing the event).**
 
 ## Example
 This example shows how to define an EventHandler object that subscribes to a topic and received the events that are posted on that topic.