DIP Testbed

DIP Testbed Platform is an academic work which allows users to remotely program and experience physical, embedded devices through various virtual interfaces (uni-directional webcam stream, bi-directional serial connection stream).

N.B. This is an academic piece of work, it's rough around the edges, because time was a significant constraint.
N.B. It is not production grade in any way. It works, but it's an experiment, a prototype.

See thesis in kshaa/dip-testbed-thesis (will publish when it's finished)

Demo

Installation

This asciicast shows how to install and configure the dip_client CLI tool.

Usage (Button & LED interface)

This asciicast shows how to run Verilog on a board and interact with it using a virtual button & LED interface.
Verilog in question: ./prototypes/03-anvyl-uart-remote/main.v

Usage (MinOS interface)

This asciicast shows how to run Verilog on a board and interact with it using a virtual MinOS interface.
Verilog in question: ./prototypes/06-anvyl-min-os/main.v

A high-level, technical description of what this demo contains is as follows:

• dip_client quick-run uploads compiled Verilog firmware anvyl-min-os/main.v to the DIP platform
• dip_client quick-run "forwards" the firmware i.e. the backend from the platform to the Anvyl FPGA board
• A network-attached Raspberry Pi running dip_client agent-anvyl receives this firmware upload request
• That same dip_client agent-anvyl downloads the firmware from the platform and uploads it into the board and responds successfully
• dip_client quick-run receives a successful upload response & initiates a serial monitor connection
• That same dip_client agent-anvyl initiates a serial connection to the board and starts streaming between the board and the platform
• dip_client quick-run starts a "MinOS" virtual user interface i.e. the frontend for interacting over the remote serial connection
• In this demo the frontend and backend only exchange streamed binary packets
• The content syntax for the binary packets (chunks) has been described using the BNF notation in prototypes/06-anvyl-min-os/syntax.bnf
• The different types of chunks are implemented, encoded & decoded seperately both in frontend and backend, they are:
  • LedChunk(type = 2) - Contains latest LED contents i.e. 8 bits which are sent from BE to FE
  • IndexedButtonChunk(type = 3) - Contains an index for a button in a range from 0 to 2^8
  • SwitchChunk(type = 4) - Contains latest switch contents i.e. 8 bits which are sent from FE to BE
  • TextChunk(type = 5) - Contains 32 bytes of regular UTF-8 encoded text which can be sent back and forth between FE and BE
  • DisplayChunk(type = 6) - Contains a display pixel change at a 0-based index N in a range from 0-63 and with a value in a range from 0 to (2^2)^3

A slightly more business-level description is as follows:

• Custom Verilog which uses a "MinOS" serial abstraction is uploaded to the board
• A "MinOS" virtual interface is spawned in the CLI
• The user sees blinking RGB lights in the corners of the virtual display
• The user can move two pixels around using virtual buttons
• The user can flip 8 virtual switches on and off
• Virtual LEDs show a counter when all virtual switches are off
• If any virtual switch is on then the virtual LEDs mirror the state of the virtual switches

Quick installation & usage

Download the CLI tool:

curl -L https://github.com/kshaa/dip-testbed/releases/latest/download/client_install.sh | bash

Create a local authentication session:

dip_client session-auth -u <username> -p <password>

Upload software to the platform, forward it to a hardware board, start a web video stream in a browser, run a serial connection against the board:

dip_client quick-run -f firmware.bit -b ${BOARD_UUID}

Note: This assumes usage of bash, AMD64 architecture, testbed.veinbahs.lv as default server
Note: Also the default buttonled interface is used
Note: Quick run has all of the underlying mechanics configurable, see options with quick-run --help

Detailed platform usage

Installation

• Download https://github.com/kshaa/dip-testbed/releases/latest/download/dip_client_${TARGET_ARCH}
• Store in ${PATH}
• Set executable bit

Platform access initiation

Configure academic DIP Testbed platform server:

dip_client session-static-server -s http://testbed.veinbahs.lv
dip_client session-control-server -s ws://testbed.veinbahs.lv

Authenticate:

dip_client session-auth -u <username> -p <password>

Developer usage

Upload software to platform:

dip_client software-upload -f firmware.bit

Forward software to a hardware board:

dip_client hardware-software-upload --hardware-id ${BOARD_UUID} --software-id ${SOFTWARE_UUID}

Create a serial connection to the board:

dip_client hardware-serial-monitor --hardware-id ${BOARD_UUID} -t buttonleds

Lab operator usage

Register hardware in platform:

dip_client hardware-create --name ${BOARD_NAME}

Run agent for registered hardware (allows remote access & management by platform):

dip_client agent-${AGENT_TYPE} -b ${BOARD_UUID} <AGENT_SPECIFIC_OPTIONS>

Note: For agent-specific usage, see dip_client agent-${AGENT_TYPE} --help

Documentation

• See 🌼 🌻 docs 🌻 🌼 for user-centric documentation
• See prototypes for examples of the testbed platform usage

Development

• See backend for backend implementation & usage
• See client for client and agent implementation & usage
• See database for database usage

Fun statistics

$ echo "$(date +'%Y-%m-%d-%H-%M-%S')"
2022-04-15-15-21-41
$ git clean -fxd
[...]
$ rm -rf ./backend/web/public # Not my code
[...]
$ docker run -v $PWD:/data mribeiro/cloc .
     348 text files.
     327 unique files.                                          
    4715 files ignored.

http://cloc.sourceforge.net v 1.60  T=1.22 s (221.5 files/s, 15930.4 lines/s)
-----------------------------------------------------------------------------------
Language                         files          blank        comment           code
-----------------------------------------------------------------------------------
Python                             101           1551            717           7424
Scala                              101            593            120           4088
Verilog-SystemVerilog               33            408            673           2465
HTML                                11              3              0            492
Bourne Shell                        17             91             85            378
SQL                                  2             33             28             70
make                                 1             18             15             40
XML                                  1             14              8             40
YAML                                 2              0              1             33
C++                                  1              4             14             14
-----------------------------------------------------------------------------------
SUM:                               270           2715           1661          15044
-----------------------------------------------------------------------------------