docs/getting_started.md

# Getting Started with Zedmon

To get started with Zedmon you will need to do 3 steps:
1. Connect the wiring
2. Build and upload the firmware to Zedmon
3. Build the command line utiliy

## 1. Wiring

* Connect a "Micro-USB B to USB cable" between the device and the monitoring host.
* Intercept the power of the target device and split it, connect the power source to the IN pins, and the target device to the OUT pins, s.t. all power is going through the Zedmon.

![Image of Zedmon](zedmon.jpg)

## 2. Building and Uploading the Firmware

This step needs to be done only once per Zedmon device.

### Prerequesites

Make sure that you have an `arm-none-eabi` gcc toolchain and
[`dfu-util`](http://dfu-util.sourceforge.net/) installed.

---

To install the `arm-none-eabi` gcc toolchain, download the latest version from this [link](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads), extract and add the path to `bin` into your `$PATH`.

To install dfu-util:
```bash
sudo apt-get install dfu-util
```

---

### Building

```bash
git clone https://fuchsia.googlesource.com/zedmon --recurse-submodules
cd zedmon/firmware
make
```

The builds output will end up in `./build-zedmon`.

### Uploading

To upload the firmware to zedmon, the device needs to be in DFU mode.  To enter
DFU mode:

 1. Hold down the `boot0` button.
 2. Press and release the `reset` button.
 3. Release the `boot0` button.

 Once the device is in DFU mode, you can upload the firmware with `dfu-util`:

```bash
dfu-util -a 0 -s 0x08000000:leave -D  build-zedmon/lk.bin -d 0483:df11
```

## 3. `zedmon` Command Line Utility

### Installing Dependencies

On Debian-based systems, the following command will install packages
required to build the command line utility:

```bash
sudo apt-get install golang libusb-1.0-0-dev
```

### Fetching Source

The `zedmon` utility is written in Go.  Because it is hosted on
fuchsia.googlesource.com, it can not simply be fetched with `go get`.  Instead
you'll need to check it out manually:

```bash
mkdir -p zedmonutil/src/fuchsia.googlesource.com
cd zedmonutil
export GOPATH=`pwd`
cd src/fuchsia.googlesource.com
git clone https://fuchsia.googlesource.com/zedmon
cd $GOPATH
go get fuchsia.googlesource.com/zedmon/cmd/zedmon
go install fuchsia.googlesource.com/zedmon/cmd/zedmon
```

The output executable will be in `./bin/zedmon`.

### Getting started wit the `zedmon` utility

To record a `zedmon` trace, run:
```bash
./bin/zedmon record
```
which will start a recording and it will record a power sample every 630 μsec. Send `^C` to stop. The ouput will be stored in `zedmon.csv`

The output is of the following format:
```
timestamp,shunt_voltage,bus_voltage
```

Sample output:
```
...
3381223490,0.0014124999643172487,14.06124968570657
3381224120,0.0014349999637488509,14.063749685650691
3381224749,0.0014124999643172487,14.05874968576245
...
```

For the full list of the commands run:
```bash
./bin/zedmon
```