Skip to content

Latest commit

 

History

History
127 lines (79 loc) · 7.82 KB

DeveloperNotes.md

File metadata and controls

127 lines (79 loc) · 7.82 KB
Raw

VectorPlus Developer Notes

See also: Contributing to VectorPlus

Dependencies

  • Visual Studio or a .NET Core installation (to build, run and test)
  • Docker (for containerising the app).

OS X

NB. On OS X, using docker-machine you may need to specify an upper limit for the disk that's a little larger than the default when you first initialise it - I've been working with 40Gb:

docker-machine create --driver virtualbox --virtualbox-disk-size "40000" default
eval $(docker-machine env default)

Concepts

When a Behaviour wishes to issue commands to the robot, it can place Actions in a queue to be run when the robot is free. This helps to distinguish between background Behaviour activity (ie. waiting for an event, such as an object being observed) and foreground Actions (such as moving the robot).

Unfortunately, there's a slight naming clash between Behaviours as defined by VectorPlus and Behaviours (reasonably complex pre-programmed actions that you can ask Vector to do through the SDK). To avoid confusion, the VectorPlus framework names key classes with a 'Plus' suffix.

VectorPlus will only take full control of the robot to execute individual Actions, or if a Behaviour is added that explicitly requires full control.

  • The VectorControllerPlus is responsible for managing a reasonably stable connection to Vector, until it is Disposed.
    • (Remember to DisposeAsync it once you have finished with it.)
    • It also manages full control of the robot - releasing Vector whenever it isn't needed.
  • A VectorBehaviourPlus can be added to the VectorControllerPlus. Once added, there are 3 ways for it to interact with Vector:
    • It can register itself with any Vector events it is using as triggers.
    • It enqueues some initial ActionPlus when it first connects.
    • Its main loop is started which can also enqueue actions.
  • A VectorActionPlus is the smallest unit of instruction passed to Vector.
    • It can contain any number of instructions for the robot.
    • If required (likely) it asks the VectorControllerPlus to take full control for it.

Project structure

These are the core projects in the solution:

  • VectorPlus.Lib - core functionality including a controller, and abstract implementations of action and behaviour.
  • VectorPlus.Demo.Behaviour - a library built to demonstrate how to build new behaviours and actions for VectorPlus.
  • VectorPlus.Capabilities.Vision - a library with some machine vision extensions built in.
  • VectorPlus.Console - a console tool able to launch a Controller, and mix in some of the demo behaviours.
  • VectorPlus.Web - a web application with a background service that administers a VectorControllerPlus.

There are also some testing projects:

  • VectorPlus.Capabilities.Tests
  • VectorPlus.Lib.Tests

Database setup

The project uses EF Core with SQLite.

  • See: Getting started with EF Core

  • VectorPlus.Web maintains a database context in: VectorPlus.Web.Service.Db.VectorPlusBackgroundServiceDbContext

  • It's driven by SQLite, and the database file is: vectorplus.db

It currently contains 2 tables:

  • ModuleConfig - details of the various behavioural modules the application is aware of.
  • RoboConfig - should contain 1 or 0 records, with details of the current robot connection config.

Modifying the database

To create a fresh instance of the database, or to modify the existing database, you'll need to create a new migration and/or update the database. Use the Nuget Package Manager console to perform these actions for the VectorPlus.Web project.

Creating a migration

Either modify VectorPlusBackgroundServiceDbContext, add new classes, or change the classes that currently map to database tables: ModuleConfig, RobotConfig

Once ready, create a migration using the Package Manager Console with the VectorPlus.Web project selected:

  • Add-Migration GiveYourMigrationANameHere -Context VectorPlus.Web.Service.Db.VectorPlusBackgroundServiceDbContext

Applying migrations / updating the database

To run the migration changes to the database, run the following in the Package Manager Console:

  • Update-Database

OS X

Visual Studio for Mac needs a little extra help, as the Nuget Package Manager Console doesn't seem to be easily available. First, install this Nuget Package Manager Console extension.

Building Behaviours

Behaviours are designed to run in the background, waiting for triggers or events before they cause the robot to take action.

Behaviours must implement IVectorBehaviourPlus, and can inherit from AbstractVectorBehaviourPlus (recommended).

To build a new Behaviour, inherit AbstractVectorBehaviourPlus and implement the abstract methods and properties. See the IVectorBehaviourPlus interface for details of the purpose of these methods and properties.

There are plenty of examples illustrating the lifecycle of a Behaviour in the VectorPlus.Demo.Behaviours project.

When enabled, a Behaviour will be assigned to the running VectorPlusController, using SetControllerAsync. For Behaviours that inherit from AbstractVectorBehaviourPlus the following then occurs:

  • The Behaviour has an opportunity to register with the Robot's events (implement RegisterWithRobotEventsAsync).
  • The Behaviour has an opportunity to issue commands to the Robot or Controller as soon as it connects (implement IssueCommandsOnConnectionAsync).
  • The Behaviour's main loop is called. This doesn't have to do anything, but the Behaviour needs a main loop, this runs on a separate thread (implement MainLoopAsync).

When running, the Behaviour may interact with the Robot directly through controller.Robot, but it is normally expected to enqueue an IVectorActionPlus which can then be scheduled by the controller (able to ensure that it has full control of the robot if required, and manage other shared resources such as Frame Processors or object tracking).

A normal (if simple) implementation might first register for an event (such as a seen face), and then when the delegate method provided to the event is called, to enqueue an action (such as some spoken words or a gesture).

On disable or disconnection from the robot, the following occurs:

  • The robot's main loop receives a Cancel on its CancelToken.
  • The Behaviour should unregister from any of the Robot's events that it was registered for (implement UnregisterFromRobotEventsAsync).

Building a Plugin

VectorPlus will scan the DLLs, provided in a plugin zip file, for classes that implement IVectorPlusBehaviourModule. These will then each be loaded as a behavioural module - with any number of assigned Behaviours. Details in the module will be made visible to the user through the UI.

  • Build your plugin project against the latest versions of VectorPlus.Lib (and VectorPlus.Capabilities.Vision, if required).
  • Implement some IVectorPlusBehaviour and IVectorPlusAction classes.
  • Implement at least one IVectorPlusBehaviourModule that references the behaviours you have created.
  • Zip the bin/Debug directory (or bin/Release directory if this is a release version).
  • You won't need to include the VectorPlus.Lib.* and VectorPlus.Capabilities.Vision.* files, but it won't do any harm - other than to inflate your zip.
  • Test the new zip by launching the VectorPlus web app, and uploading the zip into it.
  • It will unzip the file and read through the DLLs inside - looking for non-abstract classes that implement IVectorPlusBehaviourModule.