diff --git a/README.md b/README.md index 7b59681..4542982 100644 --- a/README.md +++ b/README.md @@ -6,46 +6,94 @@ (https://coveralls.io/r/glidernet/ogn-python) A python module for the [Open Glider Network](http://wiki.glidernet.org/). -The submodule 'ogn.gateway' is an aprs client, saving all received beacons -into a database with [SQLAlchemy](http://www.sqlalchemy.org/). -Other submodules process this data. +The submodule 'ogn.gateway' is an aprs client which could be invoked via a CLI +or used by other python projects. +The CLI allows to save all received beacons into a +[sqlite](https://www.sqlite.org/)-database with [SQLAlchemy](http://www.sqlalchemy.org/). +An external python project would instantiate ogn.gateway and register a custom callback, +called each time a beacon is received. -To schedule tasks like fetching ddb data, -[Celery](http://www.celeryproject.org/) with [Redis](http://www.redis.io/) is used. +[Examples](https://github.com/glidernet/ogn-python/wiki/Examples) -## Installation and Setup -1. Install python requirements +## Usage - python module +Implement your own gateway by using ogn.gateway with a custom callback function. +Each time a beacon is received, this function gets called and +lets you process the incoming data. + +Example: +```python +#!/usr/bin/env python3 + +from ogn.model import AircraftBeacon, ReceiverBeacon +from ogn.gateway.client import ognGateway + + +def process_beacon(beacon): + if type(beacon) is AircraftBeacon: + print('Received aircraft beacon from {}'.format(beacon.name)) + elif type(beacon) is ReceiverBeacon: + print('Received receiver beacon from {}'.format(beacon.name)) + + +if __name__ == '__main__': + gateway = ognGateway(aprs_user='N0CALL') + gateway.connect() + + try: + gateway.run(callback=process_beacon, autoreconnect=True) + except KeyboardInterrupt: + print('\nStop ogn gateway') + + gateway.disconnect() +``` + + +## Usage - CLI +### Installation and Setup +1. Checkout the repository + + ``` + git clone https://github.com/glidernet/ogn-python.git + ``` + +2. Install python requirements ``` pip install -r requirements.txt ``` -2. Install redis for asynchronous tasks ('ogn.collect.\*') +3. Install redis for asynchronous tasks (like takeoff/landing-detection) ``` apt-get install redis-server ``` -3. Create database +4. Create database ``` ./manage.py db.init - alembic stamp head ``` -## Running the aprs client and task server -This scripts run in the foreground and should be deamonized +### Running the aprs client and task server +To schedule tasks like takeoff/landing-detection (`logbook.compute`), +[Celery](http://www.celeryproject.org/) with [Redis](http://www.redis.io/) is used. +The following scripts run in the foreground and should be deamonized (eg. use [supervisord](http://supervisord.org/)). -``` -# start aprs client -$ ./manage.py gateway.run -# start task server (make sure redis is up and running) -$ celery -A ogn.collect worker -l info -``` +- start aprs client -## manage.py - CLI options + ``` + ./manage.py gateway.run + ``` + +- start task server (make sure redis is up and running) + + ``` + celery -A ogn.collect worker -l info + ``` + +### manage.py - CLI options ``` usage: manage.py [.] [] @@ -58,8 +106,9 @@ optional arguments: available commands: [db] + drop Drop all tables. import_ddb Import registered devices from the DDB. - import_file Import registered devices from local file. + import_file Import registered devices from a local file. init Initialize the database. [gateway] @@ -74,38 +123,22 @@ available commands: [show.receiver] hardware_stats Show some statistics of receiver hardware. - list_all Show a list of all receivers. + list_all Show a list of all receivers (NOT IMPLEMENTED). software_stats Show some statistics of receiver software. ``` Only the command `logbook.compute` requires a running task server (celery) at the moment. -## TODO -- [x] Write celery backend and add task 'fetchddb' -- [x] Rewrite manage.py with or flask-script -- [x] Rename existing cli commands -- [x] Document/Improve cli commands -- [ ] Separate settings from module (currently at ogn/command/dbutils.py) -- [ ] Enable granular data acquisition (eg. store receiver beacons only) -- [x] Future Database-Migrations: Use Alembic? - - [x] Rename 'Flarm' to 'Device'? - - [x] Rename self.heared\_aircraft\_IDs (lowercase) in aircraft\_beacon - - [x] Rename self.heared\_aircraft\_IDs -- [x] Fix command/logbook.py (@Meisterschueler?) -- [ ] Introduce scheduled tasks with 'celery beat' (eg. updateddb) ### Scheduled tasks - ogn.collect.database - - import_ddb - Import registered devices from the ddb - - import_file - Import registered devices from a local file + - `import_ddb` - Import registered devices from the ddb + - `import_file` - Import registered devices from a local file - ogn.collect.receiver - - populate - generate Receiver table (not implemented) + - `populate` - generate Receiver table (NOT IMPLEMENTED) - ogn.collect.logbook - - compute - generate TakeoffLanding table + - `compute_takeoff_and_landing` - generate TakeoffLanding table -## How to use virtualenv -``` -$ sudo apt-get install python-virtualenv -$ virtualenv env -$ source env/bin/activate +## License +Licensed under the [AGPLv3](LICENSE).