# ISM VM0 Z7000 Development Guide (v1.0)

## Introduction

The GomSpace z7000 is a zynq based SDR, three of which will be flown as payloads on the ISM VM0 mission. This guide will instruct how to build images for each of the three targets from source code. It will also provide information on upgrading images on ground and in flight.

## Setting up the build environments

### For Yocto builds
Yocto is used to build the full system images which can be programmed onto the z7000s.

Depending on target, the versions of Yocto used are `sumo` and `thud`. Both require an Ubuntu 18.04 host and a number of packages to be installed.

To allow development on other hosts a docker container can be used instead.

#### Using your native host environment
* Your host must be Ubuntu 18.04.
* Install the following packages

sudo apt-get install locales \
python \
python3 \
git \
binutils \
gcc \
chrpath \
texi2html \
g++ \
make \
gawk \
cpio \
diffstat \
texinfo \
wget

#### Using the docker environment
* Install docker on your host machine.
* Add your user to the `docker` group.

sudo groupadd docker
sudo usermod -aG docker $USER

* Build/Add the yocto sumo image to your local docker registry

sudo ./docker/build-docker-image.sh

### SDK

The SDK is a build output from the Yocto project. It contains shared libraries and their headers which will be available available on the spacecraft. To help manage the different versions of z7000 SDK which may get created over the course of development we've decided to add an installed version of it to each release.

To install the SDK you will need to create a symlink. The SDK expects itself to be installed in a specific location (`/opt/sdk-z700`). This assumes the `vm0` development release was extracted to your home directory.

sudo ln -s ~/vm0-z7000-v1.0/sdk /opt/sdk-z7000

After receiving a new development release you will need to once again update the symlink.

## Building Z7000 images

There are two image recipes which need to be built for each Z7000 SDR.
* `mission-image` which targets the main eMMC payload image.
* `nanomind-recovery-image` which targets the recovery image.

Each of these recipes can be built for three different machines.
* `vm0-p1-z7030-nv2` (payload 1)
* `vm0-p7-z7030-nv2` (payload 7)
* `vm0-msdr-z7030-nv2` (mission sdr and payload 4)

While this document won't detail how to use Yocto, an example of the command used to build the mission image for payload 1 is

cd yocto
TEMPLATECONF=../meta-mission/conf/ source ./poky/oe-init-build-env
MACHINE=vm0-p1-z7030-nv2 bitbake mission-image

For ease of development some scripts have been provided to make this process quicker.

### Docker build scripts
Build the payload and recovery image for one or all targets.

./build-vm0-docker.sh [target]

Valid fields for `target` are `all` `msdr` `p1` `p7`

## Building applications using the SDK

You can build applications outside of Yocto by using the installed SDK.

The SDK environment can be sourced by running

source /opt/sdk-z7000/environment-setup-cortexa9hf-neon-gomspace-linux-gnueabi

Sourcing the environment can break dependencies of other programs which you might run in your shell. One example of this is the python version changing enough to break mercurial. To avoid this a bash function can be created which runs a given command in the sdk environment before returning to normal system one.

function sdk-z7000 {
# Run this command in a new shell
        (
        # Exit on any error
        set -e
        # Source the SDK environment
        source /opt/sdk-z7000/environment-setup-cortexa9hf-neon-gomspace-linux-gnueabi
        # Mitigate gen1 build system issue
        unset CPPFLAGS
        # Run the command
        $@
        )
}

Example of using the function to build the MSDR datahandler app.

sdk-z7000 make -C ISML_vm0_dh_mission_p4p5_z7000 force target

## Programming the Z7000
Yocto build artefacts are found under
`yocto/build/tmp/deploy/images/<machine-name>/`.

If using 19.10 SDK the files needed to program the recovery and payload images of the z7000 are:
* `nanomind-payload-image.emmc`
* `nanomind-recovery-image.nor.ubi`
* `targets.yaml`
* `flash-dfu.py`

If using the 20.01 SDK they are:
* `nanomind-recovery-image.nor.ubi`
* `nanomind-payload-image-boot.vfat`
* `nanomind-payload-image.ext4`
* `targets.yaml`
* `flash-dfu.py`

Please read the GOMSpace Z7000 manual for instructions on how to program.

## Yocto Development
The release includes a number of meta layers. `meta-gomspace*`, `meta-openembedded`, `meta-xilinx`, and `poky` are layers included from the GOMSpace 19.10/20.01 z7000 sdk release. These have not been modified.

`meta-bal` is a layer containing general recipes created by Bright Ascension (BAL).

`meta-bal-z7000` contains recipes created by BAL which are specific to the z7000 and build upon Gomspace's layers.

`meta-mission` is a layer made for the VM0 mission. It defines the new payload image recipe as well as the target machines. This layer is also used to configure the gen1 data handler recipes and change the z7000 monitor default parameters on a machine specific basis.

## Image management

There are 3 software components to use:
* BootControl (on MSDR is called `platform.z7000.BootControl`)
* Gen1Dh (on MSDR is called `platform.z7000.Gen1DhControl`)
* ArchiveLaunch (on MSDR is called `payload.App`)

### BootControl
Manages bitstreams and kernel payload specifics. Similar to F1, you upload a tar.gz file which contains; kernel image, bitstream, device tree and uEnv.txt. You then use the FileToRss component to write the tar.gz to a file on the FS. You can then invoke the `extractArchiveToBoot` action in the BootControl component which will extract the tar.gz to the payload MMC /boot partition. You can invoke a reboot from this component to load into the updated images.

#### Boot image creation

tar -C path/to/boot/folder -czvf example-boot.tar.gz .

### Gen1Dh
This deals with the management of primary Data Handlers. Similar to F1, you upload a tar.gz file which contains a single file called `gen1-dh`. You then use the FileToRss component to write the tar.gz to a file on the FS. You can then set the primary path parameter to update the symlink in /tmp/gen1-fs/primary to point to the primary image and can restart the Gen1-DH, which will switch to the primary image by invoking the exit action. If a primary image exists then upon a power cycle/restart it will still be loaded and you do not need to invoke the exit action.

#### Primary DH image creation

mv z7000-primary-dh-image gen1-dh
tar -czvf example-gen1-dh.tar.gz gen1-dh

### ArchiveLaunch
Handles the path of the payload application and allows the user to start, stop and reset the payload application.

By default the archive launcher will
* Unpack the archive to `/tmp/payload`
* Upon start, execute `/bin/sh /tmp/payload/start.sh`
* Upon stop, execute `/bin/sh /tmp/payload/start.sh`

#### Payload image creation

tar -C path/to/payload/folder -czvf example-payload.tar.gz .