Grace Development Report

Welcome to the documentation pages of the Grace!

You can find here detailed information about the (sub)product, hereby mentioned as "module", from a high-level vision to low-level implementation decisions, a kind of Software Development Report (see template), organized by discipline (as of RUP):

• Business modeling
  • Product Vision
  • Elevator Pitch
• Requirements
  • Use Case Diagram
  • User stories
    • Implemented
    • To be Implemented
  • Domain Model
• Architecture and Design
  • Logical Architecture
  • Physical Architecture
  • Prototype
• Implementation
• Test
• Configuration and Change Management
• Project Management
• Installation Guide
  • Prerequisites
  • Building
  • Running
  • Optional Resources

So far, contributions are exclusively made by the initial team, but we hope to open them to the community, in all areas and topics: requirements, technologies, development, experimentation, testing, etc.

Please contact us! Thank you! ☺️

Mafalda Santos
Diogo Silva
Liliana Almeida
João Luz

---

Product Vision

Grace is an assistant to guide you throughout the conference. Besides that, it can act as a host and entertainer between events to make your experience truly memorable!

---

Elevator Pitch

Conferences are becoming increasingly important in what it comes to establishing new professional connections. This means there's a bunch of them which makes it harder and harder for them to stand out and become memorable and unique.

Grace, our telepresence robot, was created to make the participants' experience unforgettable. We can promise they will never feel bored when Grace's wandering around the venue ready to connect and, hopefully, cheer everyone up.

So, are you coming to the conference to enjoy the company of Grace?

---

Requirements

The app should be able to provide a fully functional interface to remotely control the assistant. It should also allow the administrator - who controls it - to see its surroundings using GraceVision. The conference participant can use the app to summon Grace.

Use Case Diagram

Summon Grace

• Actor: Conference Paticipant.

• Description: Participant pushes a button that summons Grace, making it go meet the former.

• Preconditions and Postconditions: For Grace to meet the summoner, it can't be busy responding to other user requests.

• Normal Flow:
    1. User: pushes button.
    2. System: gets the request and replies with a confirmation that Grace is on its way.
    3. User: gets the feedback.
    4. System: sends Grace.
    5. User: meets Grace.

• Alternative Flows and Exceptions:
    1. User: pushes button.
    2. System: gets the request and replies with a confirmation that Grace is on its way.
    3. User: gets the feedback.
    4. System: sends Grace.
    5. User: cancels the request.
    6. System: receives the request and sends Grace back.

          If Grace is unavailable, the system sends feedback accordingly and the user is put on a waiting list.

Move Grace Around Manually

• Actor: Robot Controller.

• Description: The controller has two input methods at their disposal - a joystick and a slider - to manipulate the direction and speed of Grace, respectively. Optionally, they can toggle GraceVision ON or OFF, allowing them to visualize Grace's route.

• Preconditions and Postconditions: Grace has to be set to "Manual Mode" beforehand.

• Normal Flow:
    1. Admin: moves the joystick in the intended direction and adjusts the speed slider.
    2. System: gets the request and performs the adequate action.
    3. Admin: watches Grace move through GraceVision.
  

• Alternative Flows and Exceptions:
    1. Admin: toggles GraceVision OFF.
    2. System: gets the request and stops transmitting GraceVision.
    3. Admin: moves the joystick in the intended direction and adjusts the speed slider.
    4. System: gets the request and performs the adequate action.
    5. Admin: observes Grace's behavior directly in person.
  

          If Grace stops receiving commands after a specific interval of time, it stops moving to avoid colliding. If GraceVision is turned ON and for an unexpected reason it stops working, the same behavior occurs.

User Stories

This section will contain the requirements of the product described as user stories, organized in a global user story map with user roles or themes.

There are two main user roles: the conference participant and the administrator. The former summons Grace and the latter controls it.

Implemented

1. As an administrator, I should be able to make the robot move.

        Given that I'm controlling the robot
        When I press a keyboard key
        Then the robot will act accordingly.

  Value Category: Must Have
  Effort: M

2. As an administrator, I should be able to change the robot's speed.

        Given that I'm controlling the robot
        When I change the slider position
        Then the robot will change its speed accordingly.

  Value Category: Must Have
  Effort: L

3. As an administrator, I should be able to see the robot's route.

        Given that I'm using the app
        When I'm controlling the robot
        Then I should see where the robot is heading.

  Value Category: Must Have
  Effort: XL

4. As an administrator, I should be able to interact with the "welcome app page".

        Given that I open the app
        When I push the "Control" button
        Then I expect the app to open a new page with the controller.

  Value Category: Could Have
  Effort: M

5. As an administrator, I should be able to control the robot's movement with the app's built-in joystick.

        Given that I'm controlling the robot
        When I manipulate the joystick
        Then the robot will act accordingly.

  Value Category: Must Have
  Effort: XL

To Be Implemented

6. As a user, I should be able to perform a security handshake with the robot.

        Given that the robot is near me
        When I scan its QR code
        Then the robot should greet me.

  Value Category: Could Have
  Effort: M

7. As a user, I should be able to call the robot.

        Given that I'm using the conference app
        When I push the "Call" button
        Then the robot should come to me.

  Value Category: Could Have
  Effort: M

8. As an administrator, I should be able to change the robot mode to automatic.

        Given that I'm controlling the robot
        When I push the "Automatic" button
        Then the robot enters standby mode.

  Value Category: Could Have
  Effort: M

Domain model

---

Architecture and Design

The architecture of a software system encompasses the set of key decisions about its overall organization.

• Robot: Uses mechanical parts controlled by an Arduino that is connected to a Raspberry Pi through USB.

• Raspberry Pi: Runs Robot Operative System (ROS) on Raspbian (ROSberryPi) that interprets commands received through Sockets and sends it to the robot.

• Mobile App: This the frontend component of the system, used by the user/admin to communicate with Grace through Sockets.

Logical Architecture

The mobile application will allow the user/admin to control the robot's moves (via joystick). Depending on the indicated move, the app will send a different message to the "publisher node" (explained next) and therefore to the robot, through a Socket.

On the Robot Operative System (ROS) Melodic side of the project, two nodes are communicating under the Publisher-Subscriber protocol. One of them (publisher) will be receiving data from a Socket, translating them into a geometry_msgs/Twist type of message and publishing them to the cmd_vel topic. The other node (subscriber) will be using the received data to give instructions to the robot's motor.

Physical Architecture

For Grace to move, there are several mechanical parts powered by two motors and batteries. These parts are controlled by an Arduino that is connected to a Raspberry Pi 4 through USB. The RPI is running Robot Operative System (ROS) Melodic on Raspbian Buster (ROSberryPi) and contains a ROS package to interpret commands received through Sockets and another to control the motion of the robot. Such instructions are input from a mobile app used by the user/admin, which was built with Flutter, an open-source UI software development kit that builds natively compiled applications from a single codebase.

Prototype

Iteration #1

• User Story #1: a ROS node was implemented to translate keyboard inputs into messages that can be read by a second node in charge of instructing the robot's motor movements.

Iteration #2

• User Story #5: same as iteration #1, but instead, the message is input from a joystick present in the mobile app, using a socket to ROS's node, translating the user's intent into valid commands. This iteration allows the user to control the robot's angular speed and direction in a more natural and precise way.

Iteration #3

• User Story #2: same as iteration #2, but with a slider in charge of wielding the linear speed of the robot.

• User Story #4: it becomes possible to choose the type of interaction the user or administrator has with Grace (calling or controlling).

Iteration #4

• User Story #3: Grace is now able to livestream video to the app, thus making the operator capable of seeing the robot's route.

---

Implementation

Our project has two core code 'modules' that complement each other (which can be found here).

• The ros_nodes section handles Grace's communications and controls.
• There's also the app section that allows the user to either control or call the robot remotely.

---

Test

Most of the time we didn't have an assembled robot, so we used a Gazebo Simulator (a 3D dynamic simulator) developed for Conde, a predecessor of Grace. This way, we managed to test the robot's main controls (joystick and slider) as they were being reproduced accurately in there.

---

Configuration and Change Management

We will use a very simple approach, just to manage feature requests, bug fixes, and improvements, using GitHub issues and following the GitHub Flow.

---

Project Management

Software project management is an art and science of planning and leading software projects, in which software projects are planned, implemented, monitored and controlled.

For this we used Trello.com, a simple project management tool capable of registering tasks, assign tasks to people, add estimations to tasks, monitor tasks progress, and therefore being able to track our project.

The following image shows our project's progress:

First Iteration

Second Iteration

Third Iteration

Fourth Iteration

---

Installation Guide

Prerequisites

• Install Robot Operative System (ROS) Melodic. We used specifically ROSberryPi, a ROS Melodic distro for Raspbian Buster, but any Ubuntu version will do (Ubuntu 18.04.3 LTS is recommended).

• Install Motion, a video streaming software solution essential for the GraceVision feature. You can do this by running the following command:

$ sudo apt-get install motion

• Find the Raspberry Pi's IP address. You will need this information in order to remotely control Grace through the app.

• Once that is done, simply replace the file motion.conf in the /etc/motion/ directory by this one. Repeat the same process with the /etc/default/motion file by replacing it by this one.

$ hostname -I

Building

Copy the files located here into the src folder inside the catkin workspace and compile it.

$ cd catkin_workspace
$ catkin make

Running

First, you must have a roscore running in order for ROS nodes to communicate. It is launched using the roscore command.

$ roscore

The rosrun process allows you to run Grace's executable in an arbitrary package from anywhere without having to give its full path or cd/roscd there first.

$ rosrun grace keyboard_listener

Optional Resources

• It is possible to use this simulator to test the robot's behaviour without an assembled robot.