Merge pull request #16 from FaradayRF/develop

Pull in all Version 0.0.1 Commits

.travis.yml

@@ -0,0 +1,9 @@
+sudo: required
+dist: trusty
+language: python
+python:
+- '3.5'
+install:
+- "~/virtualenv/python3.5/bin/pip3 install -r requirements.txt"
+script:
+- "~/virtualenv/python3.5/bin/flake8 --exclude docs/ ."

README.md

@@ -1,2 +1,72 @@
 # faradayio-cli
-Command Line Interface implementation of the faradayio module
+[![Build Status](https://travis-ci.org/FaradayRF/faradayio-cli.svg?branch=master)](https://travis-ci.org/FaradayRF/faradayio-cli) [![Gitter](https://img.shields.io/gitter/room/nwjs/nw.js.svg)](https://gitter.im/FaradayRF/Lobby)
+
+The `faradayio-cli` package provides a command line implementation of the [`faradayio`](https://github.com/FaradayRF/faradayio) module. Like the `faradayio` module this program is also radio agnostic and will work with any RF module that accepts serial port SLIP encoded IP frames. Running `faradayio-cli` results in a TUN/TAP adapter being implemented which persists as long as the program is running. This module then redirects any packets destined for the IP range assigned to the TUN/TAP adapter to the serial port specified.
+
+The main use of `faradayio-cli` is to provide access to the FaradayRF Faraday radio using standard IP packets. It makes the Faraday radio appear as a normal network interface. Below is an example of `faradayio-cli` providing a network interface `KB1LQC-1` for IP addresses `10.0.0.1` through `10.0.0.255` where the TUN adapter itself is located `10.0.0.1`.
+
+![](docs/images/ubuntuConnectionInfo.png)
+## Installation
+Install from PyPi for general use. If you would like to develop with the project them please follow these instructions to setup a virtual environment with a fork of the project and install the project in editable mode.
+
+### Recommended Environment
+`faradayio-cli` was developed and tested with the following environments
+
+* Ubuntu 16.04
+* Python3
+* `faradayio` version `0.0.2` or greater
+
+### PyPi
+To install `faradayio-cli` simply install with `pip3`
+```
+pip3 install faradayio-cli
+```
+### Git Repository Editable Mode
+```
+$ git clone [email protected]:FaradayRF/faradayio-cli.git
+$ cd faradayio-cli
+$ pip3 install -r requirements.txt
+$ pip3 install -e .
+```
+## Usage
+To run `faradayio-cli` one must be a `sudo` user due to the Linux requirements for TUN/TAP software. Additionally, if you are using a virtual environment you must also explicitly call the virtual environment installation of `faradayio-cli`
+
+### Basic Usage
+
+`faradayio-cli [-h] [-l] [-p PORT] callsign id`
+
+You are required to provide a `callsign` and `id` number as shown in the examples below. The `/dev/ttyUSB0` serial port is used by default and should be specified with the `--port` or `-p` option. See the Command Line Options section below for more information.
+### System Wide installation
+```
+$ sudo faradayio-cli KB1LQC 1
+Executing faradayio-cli version 0.0.1
+```
+### Virtual Environment
+```
+$ (.venv)$ sudo .venv/bin/faradayio-cli KB1LQC 1
+Executing faradayio-cli version 0.0.1
+```
+### Exiting `faradayio-cli`
+To exit, simply push `cntl+c` to perform a `KeyboardInterrupt` which will properly exit the TUN/TAP adapter.
+```
+Executing faradayio-cli version 0.0.1
+^CTUN brought down...
+```
+### Command Line Options
+Several command line options are required while others are optional. Below is an example from `faradayio-cli` version `0.0.1` which is provided when the program is run with `-h` or `--help`.
+```
+$ sudo .venv/bin/faradayio-cli --help
+Executing faradayio-cli version 0.0.1
+usage: faradayio-cli [-h] [-l] [-p PORT] callsign id
+
+positional arguments:
+  callsign              Callsign of radio
+  id                    ID number radio
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -l, --loopback        Use software loopback serial port
+  -p PORT, --port PORT  Physical serial port of radio
+```
+## FaradayRF
+This project is provided by [FaradayRF](https://www.faradayrf.com) as [GPLv3](https://github.com/FaradayRF/faradayio/blob/master/LICENSE) software aimed at the amateur radio (ham radio) community. Please join us on our [Gitter lobby](https://gitter.im/FaradayRF/Lobby) if you have any questions. Send an email to [[email protected]]([email protected]) if you would like to contact us via email.

faradayio-cli-runner.py

@@ -0,0 +1,6 @@
+"""Convenience wrapper for running faradayio-cli directly from source tree"""
+
+from faradayio_cli.faradayio_cli import main
+
+if __name__ == '__main__':
+    main()

faradayio_cli/__main__.py

@@ -0,0 +1,7 @@
+"""
+faradayio-cli.__main__: executed when faradayio-cli directory is called as
+script
+"""
+
+from .faradayio_cli import main
+main()

faradayio_cli/faradayio_cli.py

@@ -0,0 +1,114 @@
+"""faradayio-cli.faradayio-cli: provides entry point main()."""
+
+__version__ = "0.0.1"
+
+import argparse
+import serial
+import threading
+import time
+import pytun
+
+from faradayio.faraday import Monitor
+from faradayio.faraday import SerialTestClass
+
+
+def setupArgparse():
+    """Sets up argparse module to create command line options and parse them.
+
+    Uses the argparse module to add arguments to the command line for
+    faradayio-cli. Once the arguments are added and parsed the arguments are
+    returned
+
+    Returns:
+        argparse.Namespace: Populated namespace of arguments
+    """
+    parser = argparse.ArgumentParser()
+
+    # Required arguments
+    parser.add_argument("callsign", help="Callsign of radio")
+    parser.add_argument("id", type=int, help="ID number radio")
+
+    # Optional arguments
+    parser.add_argument("-l", "--loopback", action="store_true",
+                        help="Use software loopback serial port")
+    parser.add_argument("-p", "--port", default="/dev/ttyUSB0",
+                        help="Physical serial port of radio")
+
+    # Parse and return arguments
+    return parser.parse_args()
+
+
+def setupSerialPort(loopback, port):
+    """Sets up serial port by connecting to phsyical or software port.
+
+    Depending on command line options, this function will either connect to a
+    SerialTestClass() port for loopback testing or to the specified port from
+    the command line option. If loopback is True it overrides the physical port
+    specification.
+
+    Args:
+        loopback: argparse option
+        port: argparse option
+
+    Returns:
+        serialPort: Pyserial serial port instance
+    """
+    if loopback:
+        # Implement loopback software serial port
+        testSerial = SerialTestClass()
+        serialPort = testSerial.serialPort
+    else:
+        # TODO enable serial port command line options (keep simple for user!)
+        serialPort = serial.Serial(port, 115200, timeout=0)
+
+    return serialPort
+
+
+def main():
+    """Main function of faradayio-cli client.
+
+    Informs user of version being run and then sets up the program followed
+    by starting up the TUN/TAP device threads.
+    """
+    print("Executing faradayio-cli version {0}".format(__version__))
+
+    # Setup command line arguments
+    try:
+        args = setupArgparse()
+
+    except argparse.ArgumentError as error:
+        raise SystemExit(error)
+
+    # Setup serial port
+    try:
+        serialPort = setupSerialPort(args.loopback, args.port)
+
+    except serial.SerialException as error:
+        raise SystemExit(error)
+
+    # Create TUN adapter name
+    tunName = "{0}-{1}".format(args.callsign.upper(), args.id)
+
+    # Create threading event for TUN thread control
+    # set() causes while loop to continuously run until clear() is run
+    isRunning = threading.Event()
+    isRunning.set()
+
+    # Setup TUN adapter and start
+    try:
+        tun = Monitor(serialPort=serialPort, name=tunName, isRunning=isRunning)
+        tun.start()
+
+    except pytun.Error as error:
+        print("Warning! faradayio-cli must be run with sudo privileges!")
+        raise SystemExit(error)
+
+    # loop infinitely until KeyboardInterrupt, then clear() event, exit thread
+    try:
+        while True:
+            # Check for KeyboardInterrupt every 100ms
+            time.sleep(0.1)
+
+    except KeyboardInterrupt:
+        tun.isRunning.clear()
+        tun.join()

requirements.txt

@@ -0,0 +1,15 @@
+attrs==17.4.0
+faradayio==0.0.2
+flake8==3.5.0
+mccabe==0.6.1
+pluggy==0.6.0
+py==1.5.2
+pycodestyle==2.3.1
+pyflakes==1.6.0
+pyserial==3.4
+pytest==3.4.1
+python-pytun==2.2.1
+six==1.11.0
+sliplib==0.3.0
+sphinx-rtd-theme==0.2.4
+timeout-decorator==0.4.0

setup.py

@@ -0,0 +1,36 @@
+import re
+from setuptools import setup
+
+version = re.search(
+    '^__version__\s*=\s*"(.*)"',
+    open('faradayio_cli/faradayio_cli.py').read(),
+    re.M
+    ).group(1)
+
+setup(
+    name='faradayio-cli',
+    packages=['faradayio_cli'],
+    entry_points={
+        "console_scripts": ['faradayio-cli = faradayio_cli.faradayio_cli:main']
+        },
+    version=version,
+    description='FaradayRF TUN/TAP adapter command line interface',
+    author='FaradayRF',
+    author_email='[email protected]',
+    url='https://github.com/FaradayRF/faradayio-cli',
+
+    license='GPLv3',
+
+    classifiers=[
+        'License :: OSI Approved :: GNU General Public License v3 (GPLv3)',
+        'Programming Language :: Python',
+        'Programming Language :: Python :: 3',
+        'Topic :: Communications :: Ham Radio',
+        'Operating System :: POSIX :: Linux',
+        'Operating System :: Microsoft :: Windows',
+        'Operating System :: MacOS :: MacOS X',
+        'Development Status :: 2 - Pre-Alpha',
+        'Intended Audience :: Developers',
+        'Intended Audience :: Education',
+    ],
+)