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)
This asciicast shows how to install and configure the dip_client
CLI tool.
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
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 firmwareanvyl-min-os/main.v
to the DIP platformdip_client quick-run
"forwards" the firmware i.e. thebackend
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. thefrontend
for interacting over the remote serial connection- In this demo the
frontend
andbackend
only exchange streamed binary packets - The content syntax for the binary packets (
chunks
) has been described using the BNF notation inprototypes/06-anvyl-min-os/syntax.bnf
- The different types of chunks are implemented, encoded & decoded seperately both in
frontend
andbackend
, they are:LedChunk(type = 2)
- Contains latest LED contents i.e. 8 bits which are sent from BE to FEIndexedButtonChunk(type = 3)
- Contains an index for a button in a range from 0 to 2^8SwitchChunk(type = 4)
- Contains latest switch contents i.e. 8 bits which are sent from FE to BETextChunk(type = 5)
- Contains 32 bytes of regular UTF-8 encoded text which can be sent back and forth between FE and BEDisplayChunk(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
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
- Download
https://github.com/kshaa/dip-testbed/releases/latest/download/dip_client_${TARGET_ARCH}
- Store in
${PATH}
- Set executable bit
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>
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
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
- See ๐ผ ๐ป docs ๐ป ๐ผ for user-centric documentation
- See prototypes for examples of the testbed platform usage
- See backend for backend implementation & usage
- See client for client and agent implementation & usage
- See database for database usage
$ 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
-----------------------------------------------------------------------------------