stormwindy / qi-table

Qi-Table

Main repo for SDP at University of Edinburgh

Python

We'll be sticking as close to PEP8 as is reasonable. Basically, spaces instead of tabs.

C/C++

Suggested coding standard follows "Embedded C Coding Standard".

Software Setup

To get started:

$ git clone https://github.com/stormwindy/qi-table
$ cd qi-table
$ virtualenv env_qi -p python3
$ source env_qi/bin/activate
$ pip install -r requirements.txt --verbose

For venv:

$ git clone https://github.com/stormwindy/qi-table
$ cd qi-table
$ python3 -m venv env
$ source env/bin/activate
$ pip install -r requirements.txt --verbose

N.B. We'll be using virtual environments to avoid polluting your global python install and to ensure we're all running the same version of Python.

Base classes for the table/chairs are in ./base.py. These should be used wherever possible to maintain code interoperability.

App Setup

The frontend is currently using https://create-react-app.dev/ and is not hosted on the server that it communicates with.

To start the app:

$ cd app
$ cd my-app
$ npm install    //only need to do this the first time around
$ npm start

To connect, open localhost:3000 in your browser, though it should open automatically. For the app to function correctly, you need to also start the server:

$ source env_qi/bin/activate
$ cd app
$ flask run

This will open the server at localhost:5000, though you don't need this information to use the app

Note that there is currently no way to delete layouts from the database. You can do this manually by opening layouts.db in sqlite3 (this should come installed on Mac, not sure about Windows):

$ cd app
$ sqlite3 layouts.db

If you know SQL feel free to play around with it. If you just want to delete the saved layouts:

> delete from positions;
> delete from layouts;

qi-table's Issues

vision: manual obstacle mapping

As the title suggests, the next step for vision is for us to be able to map out obstacles in a room manually.
The current plan is for us to draw on photos (taken by the overhead camera) of the room, an obstacle will be returned as a list of points that represent a polygon.

It is very likely that this won't be the final implementation.

Printable Table Design

After demo 3 we have to move to produce more tables as current prototype is able to move autonomously.

Table should accommodate an Arduino 2 motor controller boards, and 2 NXT motors. A simple printable design will be added to the issue soon. There should be connection tunnels from the top of the board, which will host boards, to the end of the legs of the table, where the motors will be located.

[App] Layout Visualisation

Render layouts so that they can be displayed on Selection cards

Checksum to Ensure Packet Integrity

The architecture of the SRF module allows us to send at minimum bytes (1 word = 1 byte). However, this also results in a situation, where we cannot send/receive numbers over the serial connection, but only strings (using python). This would mean, that the number 1 would be 1 (string), which is 1 byte.

For this reason, we would need 1 byte to represent numbers. Hence we could use 0-9 number strings to represent an extra 1 byte checksum. This can be easily done by module 10 to make it in the range of 0 to 9.

[App] Setup server

Create Basic Functionality for motor movement on Arduino.

Resultant code should be able to move the motor while giving a control interface to the user. Components used are relevant cable/wireless connectors, Arduino board, motor controller, LEGO motors.

Basic implementation should include acceleration management where the motors accelerates and decelerates at a reasonable pace.

Communication Module Experiments

Work out a way for the Arduino to communicate with the base and the even another Arduino on the other shoe. This might require an separate communication module, but not necessarily.

[Vision] Locate AR Markers

[App] Retrieve layouts from database in selector

[App] Visual Editor

Allow adding new layouts via visual editor - though for now without relation to real table counts, room dimensions, obstacles, etc.

[Integration] Create room base class

Extend base.py to include information about a room (obstacles, geometry, tables, etc.)

Packet Security

The final model we came up for packet security is using a handshake at the beginning of the communication with the base. We call it a handshake. The handshake algorithm is a separate issue and will be implanted due course with the packet security. The fundamental algorithm is to discuss a random set of commands between the base and the tables (randomised by the base) and use these until the next handshake (this might be during operation or when base is restarted).

1. The base will randomise 10 unique commands in a way that all directions is assigned at least one (but can be up to 3 or 7) unique numbers from 0 to 9. The randomisation is first done by randomising how many commands for each direction (left, right, forward, backward). However, for simplicity each only can have up most 3 directions allocated to them, besides the last one (eg. backwards), which would be able to have all the left over. A possible algorithm might allow to not always use all the 10 commands but only a random amount (eg. backwards might be able to have 3 unique commands, but it gets assigned only 1, hence there are would be 2 unused unique command)
2. During the handshake the base sends the 10 unique commands with the corresponding directions
3. The table sends back the same information as received (part of the handshake, but the table already has an ID).
4. If the sent and received matches the base either sends ACK (acknowledge) or goes back to (2.)
5. The table on receiving the ACK flag, it will send back a Ready To Send flag back, on the other hand if the received information in any ways is not correct or incomprehensible, then the table could send a flag for that (What flag), where the base jumps back to (4.).

An example transmission during the handshake divided to commands (but sent as one), is seen below with their explanations.

Command	Meaning
L0	0 means Left
L2	2 means Left
R6	6 means Right
R4	4 means Right
R1	1 means Right
F9	9 means Forward
F8	8 means Forward
B3	3 means Backwards
B7	7 means Backwards
B5	5 means Backwards

The maximum bytes transmitted in a single transmission during the handshake: 1 byte * 2*10 = 20 bytes

If the above transmission is sent by the base then the table is expected to send it back. if the it matches (as expected), then the base sends back an ACK flag, denoted with the capital 'A' letter (1 byte).
If the acknowledge is received by the table it will send back a ready to send flag with the capital 'S' letter (1 byte). On the other hand if anything is not manageable is received by the table it will send back a What flag with the '?' symbol (1 byte). A timeout of 3 tries should be the maximum to try to initiate a connection. If it is not possible it should stop till a remote handshake is initiated by the base (e.g.: when the base is turned on)

[App] Create application skeleton

Building Basic Prototype by Lego

Build a basic Lego prototype, which can be used to initially host an Arduino (+ shield), motor control, a motors and the wheels (2 motorised and 1 or 2 just normal). Make it possible to add AR image on two corners on the top surface.

Research Final Large Shoe Design

This is some extra work on top of the lego prototype design. The aim of this is to make sure that if time is available, then we can swiftly at least showcase an example shoe for a full sized table. The research will include the design structure of the shoe, the communication modules, the wheels, the motor control and the motor itself. On top of the research, by the end of this issue, there should be a good idea about the price and the exact components needed with a model being drawn up.

Burger Control Loop and Command Support

1. Implement server code to enable command control loop with burger.

2. Implement burger motor control interface along with communications interface with ROS.

Base-Table Communication

The very initial design specification for the wireless communication between the base (central server) and the tables are as follows. This initial design is only for one table, which can be scaled up later on depending on the device being used. The whole of the design is expected to be created/programmed fully by the hardware team, with inputs from the Software team.

The Base

1. Base is sending periodic commands to tables (Left, Forward, Right, Reverse) with 2-bit sequence number making sure that the right one was received
2. The table is expected to acknowledge that it received the command with the 2-bit command sequence number (this later on might also need to include the table number)
   i. If ACK is received, continue
   ii. If not received ACK, send again with same sequence number
   iii. If not received ACK even after X many resends, communication ERROR thrown
3. If something goes wrong on the side of the base, an Emergency shutdown can be sent to stop the table(s)
   i. If the ERROR is only for a set of tables (e.g.: vision system does not detecting them), the EMERGENCY shutdown is sent to the relevant tables
   ii. If it is effecting all the tables, the EMERGENCY shutdown is sent to all

The Tables

1. Table is receiving periodical commands from base, only after receiving or not receiving will it act on the information (to avoid segmented travel)
   i. If the command received, EXECUTE it
   ii. If no command received, wait up until the end of the timeout for receiving it
   iii. If no command received by the end of the timeout, STOP the table
2. Table acknowledges the received command with the 2-bit sequence number (later on maybe with table number, e.g.: T01)
3. If something goes wrong on the side of the table send an ERROR code (potentially with table number)

Command Packets
Below is an example command packet structure for going Left, Right, Forward and Backwards/Reverse. Please note that the sequence numbers are randomly generated.

Sequence Number (2 bit)	Command
11	L
01	R
11	F
00	B

Acknowledge Packets
Below is an example acknowledge packet structure for the sequence number 01.

Sequence Number (2 bit)	Acknowledge/Command
01	A

Mischievous Packets
These packet types will include error codes and other types, which do not fit into the above categories. Please note that depending on the device being used, it might be a good idea to implement the same procedure for these kind of packets as for commands with a timeout period.

Sequence Number (2 bit)	ERROR
01	E

Encoding of Commands/Acknowledges
Depending on the type of communication used, it might be more efficient to encode the commands, acknowledges and errors into bits. At this early stage there are 4 commands, 1 acknowledge and 1 error. The 6 payloads can be represented with 3 bits (=8 different values)

Payload	Encoded Value
000	A (Acknowledge)
001	B (Backwards)
010	F (Forward)
011	L (Left)
100	R (Right)
111	E (ERROR)

Realistic Table Prototype

By Demo 2, there is an urgent need to have at least one, but preferably two realistic Lego table prototypes with the new motors. The prototype should be robust, with the widths/height ratio being different (not a square). The two separate prototypes as per the preference of the path finding team, should be the same size (it might change in the future, so check with them). We will (continue to) start off by using only two motors and four wheels as before, but if it is impossible to solve (even with different kind of wheels on driven and non-driven wheels) then it must be actuated by four motors.
Try to check exhaust all possibilities before moving onto a four motor set-up!

[Pathfinding] Basic pathfinding

[HW] New Motor Controller

During Sprint 1, it became clear that we cannot continue the use of the current low power motors. This means that we urgently need to work out a similar communication with a new type of motors. The new motors should be chosen in collaboration with the hardware prototyping team to meet their specification. On top of this, the motor(s) should be readily available in a short time (preferably from Garry and/or our lockers). This motor control will later on communicate with a separate program structure (module) in the Arduino, which will be responsible for receiving communication from the base server wirelessly.
Please note that in a worst case scenario, we might need to put the PIs on the prototype structure to enable wireless control, so the motors need to be strong enough.

Multi-Agent control support

Underlying server code should be able to support multi agent control. This is planned to be handled by creating a multiprocessed control loop that queues up commands to a shared list. A threaded method will write these commands to the RF port as they come in.

[App] App-Server communication

[App] Add new layouts through app

[App] Edit existing layouts

Currently the editor only allows for the creation of new layouts - make it possible to modify existing ones.

[App] Real-life bounds on Editor

Make layouts produced by the Editor (and available in the Selector) adhere to real life limitations and positions values.

Create Realistic CAD design of Prototype

Learn how to use CAD (eg. AutoCAD) by creating the prototype in 3D. Later on this will be useful to create a model for the final prototype (or even when we have to 3D print something)