Basic Usage

Owned by Kavin Satheeskumar
Last updated: May 31, 2023 by Chamath Wijesekera
2 min read

This Document has been moved over to Google Drive

This is largely stolen from the GitHub Readme

Requirements

  • Python version 3.8 or newer

    • For Linux users, a python package with C headers (such as python3-dev) is necessary

    • All required packages can be installed using pip install -r requirements.txt after the repo is cloned (refer to next section)

  • Git

    • Refer to out Git tutorial for everything you need to know about this [Yet to be written]

    • Note, these instructions also assume an understanding of how to use a command line, which should also be covered in the Git Documentation

Instillation

The Omnibus library is required to run any of the sources or sinks. To install it:

  1. Clone the Omnibus GitHub Repo

    • If you have git configured with SSH, run git clone git@github.com:waterloo-rocketry/omnibus.git

    • If you don't have git configured with SSH (or you're not sure what that means), run git clone https://github.com/waterloo-rocketry/omnibus.git

  2. Enter the newly cloned Repo

    • cd omnibus

  3. Optional, but highly recommend, create a Python Virtual Environment

    • First, you will need to install python’s virtualenv library

      • pip install virtualenv

    • Then you will need to create a virtual environment

      • python -m venv [Directory]

    • Activate the virtual environment

      • For osx/linux: source [Directory]/bin/activate

      • For windows: [Directory]\Scripts\activate

  4. When you first run through these procedures, you should make sure your pip is up to date, especially is using a Virtual Environment

    • pip install --upgrade pip

  5. Similarly, you should make sure you have wheel installed (especially if you just created a Virtual Environment)

    • pip install wheel

  6. Now that you have your environment set up, you can install the dependencies needed to run omnibus

    • pip install -r requirements.txt

    • If you get a permissions error, try pip install --user -r requirements.txt instead

  7. Afterwards, you can install the omnibus library locally. For links that explain what a local library is, refer to the core library section

    • pip install -e .

    • Don't forget the .! This allows the sources and sinks (and you) to import Omnibus.

Usage

As described in the introduction, omnibus works using three components

  1. The Core Library

  2. The Source

  3. The Sink

All three of which need to be running at the same time for everything to work. For each of these components, open a terminal.

To start the core library, first navigate to the omnibus directory and run the module.

cd path/to/omnibus

python -m omnibus

All source are run using main.py, a different version of this file will exist for each source. To start the source, run it. For the source to begin operating, the core library must be running. If it isn’t the source will simply wait. Note, each source and sink may have its own requirements.txt that will need to be installed

python path/to/omnibus/sources/name/main.py

The exact same procedure works to start the sink. Note the sink waits for both the core library and the source.

python path/to/omnibus/sinks/name/main.py

One thing worth noting is that this procedure will still work if the sink is running on a different machine than the source and omnibus as long as the two machine are on the same LAN. It is common for us, during tests, to set up a local area net work, and connect two laptops to it to allow omnibus to work from a safe distance.

More on how this works in the core library section.