From 4dad284ba0becce4f4b35e61d0593f0e7270263c Mon Sep 17 00:00:00 2001 From: Luca Warmenhoven Date: Tue, 4 Jun 2024 16:58:06 +0200 Subject: [PATCH] Updated documentation --- .../Luca/diagram-pepper-abstraction.md | 88 +++++++++++++++++++ .../Luca/expert-review-tips.md | 9 -- .../Luca/expert-review.md | 11 +++ .../Luca/infrastructure-design.md | 31 +++++++ 4 files changed, 130 insertions(+), 9 deletions(-) create mode 100644 docs/personal-documentation/Luca/diagram-pepper-abstraction.md delete mode 100644 docs/personal-documentation/Luca/expert-review-tips.md create mode 100644 docs/personal-documentation/Luca/infrastructure-design.md diff --git a/docs/personal-documentation/Luca/diagram-pepper-abstraction.md b/docs/personal-documentation/Luca/diagram-pepper-abstraction.md new file mode 100644 index 0000000..c92bbbc --- /dev/null +++ b/docs/personal-documentation/Luca/diagram-pepper-abstraction.md @@ -0,0 +1,88 @@ +## Pepper Abstraction Design + +--- + +### Introduction + +The Pepper robot is a complex system that can be controlled by a variety of different actions. To make the system more +manageable, we've decided implement abstraction and encapsulation in the classes related to Pepper controls. +This way, we can easily add new action events in the future. +All these classes inherit from the `AbstractPepperActionEvent` class. + +### Problems + +1. The Pepper robot functions with a system that only allows one action to be executed at a time, per action category. +This means that, for example, when two speech actions are executed at the same time, the application will crash due +to a `RuntimeException` being thrown. Due to this fact, whenever the execution of multiple processes overlap, +the application will crash. + +2. Besides the first problem, for the Pepper robot to be able to execute any actions, it is required to have a +QiContext available. This context is only provided in a class that extends the `RobotLifecycleCallbacks` class. +This means, that whenever the class does not extend this class, the robot will be unable to execute any actions. + +### Solution + +To prevent the application from crashing, we've decided to implement a queue system in the `Pepper` class. +This system allows us to queue any new actions that need to be executed whenever another action is already +being executed. This way, we can prevent the application throwing a `RuntimeException` and thus crashing. + +To tackle the second problem, we've decided to implement a system where the Pepper class has a global variable, which +holds the current QiContext. This means, that whenever a user decides to execute an action, and no current QiContext +is available, the action will be queued until a QiContext is available. This means that we can queue several actions +at once without any exceptions being thrown. + +### Diagrams + +#### Class Diagram + +```mermaid +classDiagram + class Pepper { + -pepperActionEventQueue : ConcurrentLinkedQueue + -isAnimating : AtomicBoolean + -isSpeaking : AtomicBoolean + + +latestContext : QiContext + +addToEventQueue(AbstractPepperActionEvent event) + +provideQiContext(QiContext context) + + -processEventQueue() + } + class AbstractPepperActionEvent { + +getAction() EPepperAction + } + class PepperSpeechEvent { + +phrase : String + +locale : Locale + +PepperSpeechEvent(String phrase, Locale locale) + +getSay(QiContext context) Say + } + class PepperAnimationEvent { + +PepperAnimationEvent(String animationName) + +PepperAnimationEvent(String animationName, IAnimationCompletedListener listener) + +getAnimation(QiContext context) Animate + +animationName : String + +IAnimationCompletedListener : IAnimationCompletedListener + } + Pepper <|-- AbstractPepperActionEvent + PepperSpeechEvent <|-- AbstractPepperActionEvent + PepperAnimationEvent <|-- AbstractPepperActionEvent +``` + +#### Queue System in Pepper class + +```mermaid + +graph LR + subgraph "Pepper Class - Action Queue System" + speak[say(String phrase)\nPublic\nCreate PepperSpeechEvent] --Call method--> addQueue + animate[animate(String animationName)\nPublic\nCreate PepperAnimationEvent] --Call method--> addQueue + addQueue[addToEventQueue(AbstractPepperActionEvent event)\nPublic\nAdd provided event to event queue] --Add to queue--> queue[Event Queue\nPrivate\nQueue containing all events that\nneed to be executed] + + addQueue --Call method--> handleQueue[processEventQueue()\nPrivate\nCheck whether there is a context\navailable, and whether an event\nis currently being executed.\nExecutes the next event in the Queue] + + queue <.-> handleQueue + + provideCtx[provideQiContext(QiContext context)\nPublic\nSets global QiContext variable\nto provided context. If the context \nis not null,process the event queue] --Sets global QiContext variable--> handleQueue + end +``` \ No newline at end of file diff --git a/docs/personal-documentation/Luca/expert-review-tips.md b/docs/personal-documentation/Luca/expert-review-tips.md deleted file mode 100644 index fb147bc..0000000 --- a/docs/personal-documentation/Luca/expert-review-tips.md +++ /dev/null @@ -1,9 +0,0 @@ - -## Expert review #1 - -### Document as you go -Documenteer alle problemen die voorkomen bij het project en noteer de -oplossingen voor deze problemen. Dit kan bijvoorbeeld d.m.v. een command die -cache files verwijderd, of op welke manier je een project fixt. Dit kan toekomstige -problemen voorkomen. - diff --git a/docs/personal-documentation/Luca/expert-review.md b/docs/personal-documentation/Luca/expert-review.md index fa98e9b..cf97502 100644 --- a/docs/personal-documentation/Luca/expert-review.md +++ b/docs/personal-documentation/Luca/expert-review.md @@ -12,6 +12,9 @@ Deze classes inheriten `AbstractPepperActionEvent`. K2: Gebruikers Test +( Maak een fictief persoon die de applicatie zou kunnen gebruiken, om erachter te komen +wat ze zouden willen ) + --- Wij hebben gezamenlijk gecommuniceerd over het plan, echter is alleen @@ -32,6 +35,14 @@ Zie bestand 'infrastructure.md' K4 - Ontwerp embedded system +Documenteer het queue systeem van de Pepper class +Maak een mermaid graph LR diagram + --- Zie '/documentation/hardware/sensors' + +K5 - Embedded Software Schrijven + +Feedback: +- Is in principe K1, diff --git a/docs/personal-documentation/Luca/infrastructure-design.md b/docs/personal-documentation/Luca/infrastructure-design.md new file mode 100644 index 0000000..b327d75 --- /dev/null +++ b/docs/personal-documentation/Luca/infrastructure-design.md @@ -0,0 +1,31 @@ +### Infrastructure Design + +--- + +```mermaid + +graph TB + subgraph "Raspberry Pi" + server[NodeJS Server\nHandles requests for\nexercises] + db[Database] + server --Fetch exercise--> db + db --Exercise--> server + + end + + subgraph "Pepper Robot" + webServer[Web Server\n\nHandles incoming rotational data\nfrom ESP8266] + motionProcessor[Motion Processor\n\nProcesses rotational data,\ncompares it to the current exercise\nand shows the statistics on the screen] + motionProcessor --Send HTTP GET for Exercise--> server + server --Send exercise in JSON format--> motionProcessor + webServer --Process rotational data--> motionProcessor + end + + subgraph "Motion Sensing Device" + esp[ESP8266\n\nMeasures sensor data\nand sends it to the web server] + gyro[Gyroscope\n\nMeasures rotational data\nand sends it to the ESP8266] + esp --Send rotational data\nto Pepper Web Server--> webServer + gyro <--> esp + end + +``` \ No newline at end of file