# Getting Started

## Prerequisites

### Simulation

Simulations are run in a docker container with the image `li-cocotb-pymoku`.
You will need a docker environment with access to this image (currently unpublished).

The resulting `wave.ghw` files can be viewed with GtkWave or Surfer.

### Building bitstreams

#### Vivado
Bitstreams require a local verision of Vivado (>= 2024.2 recommended) installed
with appropriate licences configured.

**TODO**

Parts can be exteneded to package build context for a remote worker, avoiding the
need for a local Vivado installation.

### Keys

Creating barfiles that can be deployed on a Moku require them to be signed by
Liquid Instruments or with developer keys that have been enabled on the target
Moku.

See below for generating keys; these must be signed by Liquid Instruments to
enable specific devices.

## (interim) Installation

These are the current instructions until these packages are publicly available.
It does require access to the LI internal GitLab.

Put these in `requirements.txt`

    pymoku @ git+https://git.liquidinstruments.com/pymoku/pymoku.git
    pymoku-parts @ git+https://git.liquidinstruments.com/pymoku/pymoku-parts.git
    pymoku-sdk @ git+https://git.liquidinstruments.com/pymoku/pymoku-sdk.git
    docker

create a virtual environment

    python -m virtualenv venv
    source venv/bin/activate

and then run

    pip install -r requirements.txt

## Generate a signing key

This only needs to be done once, and the key will be stored in the user home directory.

    pymokusdk keys create my-key

The resulting public key will need to be signed by Liquid Instruments.

## Create a new project

    pymokusdk new MySlot --hw mokugo
    cd myslot

## Run the simulaition

    parts tests

Results will available in the `build/test-slot` folder.  Of interest will be
`wave.ghw` and `stdout.log`.  Build failures in the VHDL will be printed to the
console, but errors during execution will be `stdout.log`.

## Run a build

    parts mokugo python --stats

The resulting barfiles will be in `output/`.

## Deploying from Python

    import pymoku
    pymoku.plugins.DEV_CACHE = './output'  # reference our local output
    moku = pymoku.connect('10.0.0.1')
    moku.deploy_platform('pymoku:platform_2')  # deploy a platform (only needed once)
    myslot = moku.deploy('custom:myslot')  # this name should match the specific id used in parts.def

The `myslot` object will be created dynamically from your custom python plugin
and attached to the slot instance on the Moku.

## Deploying from the GUI

First you will need to have installed `pymoku[extras]` to include GUI support.

Then run pymoku with reference to your local `output` folder

    pymoku --dev output/

This will launch the GUI.  After connecting to a Moku and deploying a platform,
your custom implementation will be available from the functions palette (assuming
it was built for the deployed platform).

Launching the slot instance will open the applet defined by your custom python
plugin.  The default will appear as a python console.

# TODO

- [ ] 'clean' targets
- [x] Create barfiles for checkpoints to use as platforms
- [x] Don't use GPG for signatures
- [x] Use personal signing keys to sign manifests
- [x] Generate signing keys
- [ ] Auto generate "custom wrapper"
- [ ] Bitstream encryption
- [ ] Sanity check environment
- [x] Fetch checkpoints from cloud
- [x] Plugin versions (or lack of) break pymoku prioritisation
- [x] API deployment
- [x] If Git on PATH or CLI arg, add .gitignore and init repo
- [ ] Auto generate top/test bench with new generics and custom number of Ain/Aout
