-
Notifications
You must be signed in to change notification settings - Fork 1
Getting Started
This page will guide you through the process of setting up the Mercury2 Hardware Manager and User Interface. The following guides are written assuming that you're using a Debian or Ubuntu host. Other platforms may be used, but these instructions may require modification to work.
First we will install the Mercury2 Hardware Manager on a host that has direct access to your ground station's equipment. This will create a Mercury2 "substation". The Hardware Manager is responsible for interfacing with the ground station's hardware devices and managing access to the substation in coordination with the User Interface.
To get started we will create a Python virtual environment for the hardware manager. Using a virtual environment will allow the Hardware Manager to run with an isolated version of Python. This will make managing dependencies much easier.
Install virtualenv.
sudo apt-get install python-pip
sudo pip install virtualenv
Create a user and group to run Mercury2 applications.
sudo groupadd mercury2
sudo useradd -g mercury2 mercury2
sudo usermod -a -G mercury2 $USER
You will need to su your own account in order for the group permissions to take effect.
su $USER
Create directories for the Hardware Manager.
sudo mkdir /var/mercury2
sudo chown mercury2:mercury2 -R /var/mercury2
sudo chmod 775 -R /var/mercury2
Create a Python virtual environment. We will need to use Python 2.7 to support the Twisted networking library.
cd /var/mercury2
mkdir envs && cd envs
virtualenv hwm
Activate your virtual environment. After running this command your shell prompt should have (hwm) before it.
source hwm/bin/activate
Download the Hardware Manager source and switch to the develop branch.
mkdir hwm && cd hwm
git init
git remote add origin https://github.com/MichiganExplorationLab/Mercury2-HWM.git
git fetch origin
git checkout develop
Install the Hardware Manager and its dependencies.
python setup.py install
The Hardware Manager should now be installed at your ground station! As long as you're sourced into the virtual environment, you will be able to use the mercury2 command to start the Hardware Manager. On first run, the default configuration files will be copied to the /var/mercury2/hwm/config directory.
After running the Hardware Manager for the first time, the default configuration files will be copied to the config directory. configuration.yml contains general substation setup, devices.yml contains device configuration, and pipelines.yml specifies the substation's pipeline setup. Each file contains additional information and configuration examples.
If you plan on developing for the Hardware Manager (thanks!) you may find it useful to install it in development mode. This will allow changes you make to the source to be picked up automatically.
python setup.py develop
The Mercury2 Hardware Manager is supported by a full test suite. To run all unit tests, make sure that the Hardware Manager is in development mode (see above) and run the following command in the hwm directory.
trial hwm
You can also run the unit tests for a specific package, for example:
trial hwm.hardware
It is good practice to run the full test suite after making a change to verify that there were no regressions. All pushed code changes must be backed by tests! See the Twisted documentation for more about writing unit tests.
Now we will work on setting up the User Interface. This can be installed on any host that is accessible to the ground station's substations (i.e. Hardware Manager instances). The User Interface provides a web-based interface for ground station management, scheduling, and real time monitoring. It is built around the Django web framework.
We will now install the User Interface into a Python virtual environment. If you haven't done so already, create the users, groups, and directories that will be used to run the User Interface.
sudo groupadd mercury2
sudo useradd -g mercury2 mercury2
sudo usermod -a -G mercury2 $USER
su $USER
sudo mkdir /var/mercury2
sudo chown mercury2:mercury2 -R /var/mercury2
sudo chmod 775 -R /var/mercury2
The su $USER command forces a refresh of your group membership information, allowing you to write to the directory without having to log out and back in.
Next, create a Python 3.3 virtual environment for the user interface. See the Hardware Manager installation guide for information about installing virtualenv.
cd /var/mercury2
mkdir envs && cd envs
virtualenv -p /usr/bin/python3.3 ui
Activate the new virtual environment. After running this command your shell prompt should have (ui) before it.
source ui/bin/activate
Download the User Interface source code from github and switch to the develop branch.
cd ..
mkdir ui && cd ui
git init
git remote add origin https://github.com/MichiganExplorationLab/Mercury2-UI.git
git fetch origin
git checkout develop
Next we will install the User Interface's python dependencies into the ui virtual environment.
sudo apt-get install python-psycopg2
pip install -r requirements.txt
The User Interface has now been installed, however we still need to create a database for it. PostgreSQL will be used for this guide, but any database supported by Django can be used. To begin, install PostgreSQL.
sudo apt-get update
sudo apt-get install libpq-dev python-dev
sudo apt-get install postgresql postgresql-contrib
Next, create a Postgresql database and role (user) for the User Interface.
sudo su - postgres
createdb mercury2
createuser -P
You will now be prompted for information about your new Postgresql user. Set the username as mercury2 (or whatever you'd like, just substitute later on) and specify a password. You can just select "n" for the last three prompts.
Next we need to enter the Postgresql shell to give our new user database access.
psql
GRANT ALL PRIVILEGES ON DATABASE mercury2 TO mercury2;
Exit the Postgresql shell using CTRL+D and switch back to your normal user using logout.
Now that a database has been created, we need to update the configuration with the database connection information. Copy mercury2/local_settings.py.default to mercury2/local_settings.py and open it in your favorite editor. Update DATABASES with your database name, username, and password from the last step. While we're here, also update your admin user information and set a long, random secret key.
Now we just have to migrate our database tables and create a superuser Django account. We will need to supply the --settings=mercury2.local_settings argument to let Django know where to find our database settings.
python manage.py migrate --settings=mercury2.local_settings
python manage.py createsuperuser --settings=mercury2.local_settings
Simply follow the prompts to setup your Django super user. This user will serve as the primary admin account for your ground station.
The Mercury2 User Interface has now been installed! Proceed to the next section to learn how to run the server for development, or go to the Public Deployment section to instructions on how to setup Apache.
If you are developing for the User Interface, it will likely be more convenient to run Django using the development server that ships with it. If you haven't already, set DEBUG=True in local_settings.py and use the following command to start the server. Make sure that the User Interface's virtual environment has been activated first.
python manage.py runserver --settings=mercury2.local_settings
You should now be able to access the User Interface at [server IP or localhost]:8000. Once you login using your super user account at localhost:8000/users/login/ you will be able to access the admin panel at localhost:8000/admin/. If debug mode is enabled, you may notice a toolbar running down the right side of the page. This provides useful information for development including SQL query profiling (useful for identifying ORM bottlenecks) and request information.
While convenient, the development server should never be used in a production environment. See the Public Deployment section for details on how to setup Apache for production use.
The Mercury2 User Interface makes use of the SASS CSS framework. SASS makes CSS much more powerful by allowing for inheritance, variables, and mix-ins, among other things. To make style sheet compilation more convenient, we can use Compass to monitor for SCSS file changes and automatically compile our static files. Follow the instructions on Compass' website to install it. The User Interface comes with a default Compass configuration file so you can simply run compass watch from the root directory to monitor for style sheet changes.