From 0652abef022c5adeb4cd6d115c54ee5a10e39198 Mon Sep 17 00:00:00 2001 From: Cort Buffington Date: Mon, 19 Dec 2016 08:36:17 -0600 Subject: [PATCH] Descriptions added (below copyright and license area) --- hb_bridge_all.py | 231 +++++++++++++++++++++++++++++++++++++++++++++++ hb_confbridge.py | 13 +++ hb_config.py | 8 ++ hb_const.py | 6 ++ hb_log.py | 6 ++ hb_router.py | 11 +++ hblink.py | 9 ++ sub_acl.py | 8 ++ 8 files changed, 292 insertions(+) create mode 100755 hb_bridge_all.py diff --git a/hb_bridge_all.py b/hb_bridge_all.py new file mode 100755 index 0000000..765be46 --- /dev/null +++ b/hb_bridge_all.py @@ -0,0 +1,231 @@ +#!/usr/bin/env python +# +############################################################################### +# Copyright (C) 2016 Cortney T. Buffington, N0MJS +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software Foundation, +# Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA +############################################################################### + +''' +This is a very simple call/packet router for Homebrew Repeater Protocol. It +will forward traffic from any system to all other systems configured in the +hblink.py configuration file. It does not check for call contentions or +filter TS/TGID combinations. It should really only be used as a proxy to +hide multiple Homebrew repater protocol systems behind what appears as a single +repeater, hotspot, etc. + +As is, this program only works with group voice packets. It could work for all +of them by removing a few things. +''' + +from __future__ import print_function + +# Python modules we need +import sys +from bitarray import bitarray +from time import time +from importlib import import_module + +# Twisted is pretty important, so I keep it separate +from twisted.internet.protocol import DatagramProtocol +from twisted.internet import reactor +from twisted.internet import task + +# Things we import from the main hblink module +from hblink import HBSYSTEM, systems, int_id, hblink_handler +from dmr_utils.utils import hex_str_3, int_id, get_alias +from dmr_utils import decode, bptc, const +import hb_config +import hb_log +import hb_const + +# Does anybody read this stuff? There's a PEP somewhere that says I should do this. +__author__ = 'Cortney T. Buffington, N0MJS' +__copyright__ = 'Copyright (c) 2016 Cortney T. Buffington, N0MJS and the K0USY Group' +__credits__ = 'Colin Durbridge, G4EML, Steve Zingman, N4IRS; Mike Zingman, N4IRR; Jonathan Naylor, G4KLX; Hans Barthen, DL5DI; Torsten Shultze, DG1HT' +__license__ = 'GNU GPLv3' +__maintainer__ = 'Cort Buffington, N0MJS' +__email__ = 'n0mjs@me.com' +__status__ = 'pre-alpha' + +# Module gobal varaibles + + +class routerSYSTEM(HBSYSTEM): + + def __init__(self, _name, _config, _logger): + HBSYSTEM.__init__(self, _name, _config, _logger) + + # Status information for the system, TS1 & TS2 + # 1 & 2 are "timeslot" + # In TX_EMB_LC, 2-5 are burst B-E + self.STATUS = { + 1: { + 'RX_START': time(), + 'RX_SEQ': '\x00', + 'RX_RFS': '\x00', + 'TX_RFS': '\x00', + 'RX_STREAM_ID': '\x00', + 'TX_STREAM_ID': '\x00', + 'RX_TGID': '\x00\x00\x00', + 'TX_TGID': '\x00\x00\x00', + 'RX_TIME': time(), + 'TX_TIME': time(), + 'RX_TYPE': hb_const.HBPF_SLT_VTERM, + 'RX_LC': '\x00', + 'TX_H_LC': '\x00', + 'TX_T_LC': '\x00', + 'TX_EMB_LC': { + 1: '\x00', + 2: '\x00', + 3: '\x00', + 4: '\x00', + } + }, + 2: { + 'RX_START': time(), + 'RX_SEQ': '\x00', + 'RX_RFS': '\x00', + 'TX_RFS': '\x00', + 'RX_STREAM_ID': '\x00', + 'TX_STREAM_ID': '\x00', + 'RX_TGID': '\x00\x00\x00', + 'TX_TGID': '\x00\x00\x00', + 'RX_TIME': time(), + 'TX_TIME': time(), + 'RX_TYPE': hb_const.HBPF_SLT_VTERM, + 'RX_LC': '\x00', + 'TX_H_LC': '\x00', + 'TX_T_LC': '\x00', + 'TX_EMB_LC': { + 1: '\x00', + 2: '\x00', + 3: '\x00', + 4: '\x00', + } + } + } + + def dmrd_received(self, _radio_id, _rf_src, _dst_id, _seq, _slot, _call_type, _frame_type, _dtype_vseq, _stream_id, _data): + pkt_time = time() + dmrpkt = _data[20:53] + _bits = int_id(_data[15]) + + if _call_type == 'group': + + # Is this is a new call stream? + if (_stream_id != self.STATUS[_slot]['RX_STREAM_ID']): + self.STATUS['RX_START'] = pkt_time + self._logger.info('(%s) *CALL START* STREAM ID: %s SUB: %s (%s) REPEATER: %s (%s) TGID %s (%s), TS %s', \ + self._system, int_id(_stream_id), get_alias(_rf_src, subscriber_ids), int_id(_rf_src), get_alias(_radio_id, peer_ids), int_id(_radio_id), get_alias(_dst_id, talkgroup_ids), int_id(_dst_id), _slot) + + for _target in self._CONFIG['SYSTEMS']: + if _target != self._system: + systems[_target].send_system(_data) + self._logger.debug('(%s) Packet routed to system: %s', self._system, _target) + + + # Final actions - Is this a voice terminator? + if (_frame_type == hb_const.HBPF_DATA_SYNC) and (_dtype_vseq == hb_const.HBPF_SLT_VTERM) and (self.STATUS[_slot]['RX_TYPE'] != hb_const.HBPF_SLT_VTERM): + call_duration = pkt_time - self.STATUS['RX_START'] + self._logger.info('(%s) *CALL END* STREAM ID: %s SUB: %s (%s) REPEATER: %s (%s) TGID %s (%s), TS %s, Duration: %s', \ + self._system, int_id(_stream_id), get_alias(_rf_src, subscriber_ids), int_id(_rf_src), get_alias(_radio_id, peer_ids), int_id(_radio_id), get_alias(_dst_id, talkgroup_ids), int_id(_dst_id), _slot, call_duration) + + # Mark status variables for use later + self.STATUS[_slot]['RX_RFS'] = _rf_src + self.STATUS[_slot]['RX_TYPE'] = _dtype_vseq + self.STATUS[_slot]['RX_TGID'] = _dst_id + self.STATUS[_slot]['RX_TIME'] = pkt_time + self.STATUS[_slot]['RX_STREAM_ID'] = _stream_id + + +#************************************************ +# MAIN PROGRAM LOOP STARTS HERE +#************************************************ + +if __name__ == '__main__': + + import argparse + import sys + import os + import signal + from dmr_utils.utils import try_download, mk_id_dict + + # Change the current directory to the location of the application + os.chdir(os.path.dirname(os.path.realpath(sys.argv[0]))) + + # CLI argument parser - handles picking up the config file from the command line, and sending a "help" message + parser = argparse.ArgumentParser() + parser.add_argument('-c', '--config', action='store', dest='CONFIG_FILE', help='/full/path/to/config.file (usually hblink.cfg)') + parser.add_argument('-l', '--logging', action='store', dest='LOG_LEVEL', help='Override config file logging level.') + cli_args = parser.parse_args() + + # Ensure we have a path for the config file, if one wasn't specified, then use the default (top of file) + if not cli_args.CONFIG_FILE: + cli_args.CONFIG_FILE = os.path.dirname(os.path.abspath(__file__))+'/hblink.cfg' + + # Call the external routine to build the configuration dictionary + CONFIG = hb_config.build_config(cli_args.CONFIG_FILE) + + # Start the system logger + if cli_args.LOG_LEVEL: + CONFIG['LOGGER']['LOG_LEVEL'] = cli_args.LOG_LEVEL + logger = hb_log.config_logging(CONFIG['LOGGER']) + logger.debug('Logging system started, anything from here on gets logged') + + # Set up the signal handler + def sig_handler(_signal, _frame): + logger.info('SHUTDOWN: HBROUTER IS TERMINATING WITH SIGNAL %s', str(_signal)) + hblink_handler(_signal, _frame, logger) + logger.info('SHUTDOWN: ALL SYSTEM HANDLERS EXECUTED - STOPPING REACTOR') + reactor.stop() + + # Set signal handers so that we can gracefully exit if need be + for sig in [signal.SIGTERM, signal.SIGINT]: + signal.signal(sig, sig_handler) + + # ID ALIAS CREATION + # Download + if CONFIG['ALIASES']['TRY_DOWNLOAD'] == True: + # Try updating peer aliases file + result = try_download(CONFIG['ALIASES']['PATH'], CONFIG['ALIASES']['PEER_FILE'], CONFIG['ALIASES']['PEER_URL'], CONFIG['ALIASES']['STALE_TIME']) + logger.info(result) + # Try updating subscriber aliases file + result = try_download(CONFIG['ALIASES']['PATH'], CONFIG['ALIASES']['SUBSCRIBER_FILE'], CONFIG['ALIASES']['SUBSCRIBER_URL'], CONFIG['ALIASES']['STALE_TIME']) + logger.info(result) + + # Make Dictionaries + peer_ids = mk_id_dict(CONFIG['ALIASES']['PATH'], CONFIG['ALIASES']['PEER_FILE']) + if peer_ids: + logger.info('ID ALIAS MAPPER: peer_ids dictionary is available') + + subscriber_ids = mk_id_dict(CONFIG['ALIASES']['PATH'], CONFIG['ALIASES']['SUBSCRIBER_FILE']) + if subscriber_ids: + logger.info('ID ALIAS MAPPER: subscriber_ids dictionary is available') + + talkgroup_ids = mk_id_dict(CONFIG['ALIASES']['PATH'], CONFIG['ALIASES']['TGID_FILE']) + if talkgroup_ids: + logger.info('ID ALIAS MAPPER: talkgroup_ids dictionary is available') + + + # HBlink instance creation + logger.info('HBlink \'hb_bridge_all.py\' (c) 2016 N0MJS & the K0USY Group - SYSTEM STARTING...') + for system in CONFIG['SYSTEMS']: + if CONFIG['SYSTEMS'][system]['ENABLED']: + systems[system] = routerSYSTEM(system, CONFIG, logger) + reactor.listenUDP(CONFIG['SYSTEMS'][system]['PORT'], systems[system], interface=CONFIG['SYSTEMS'][system]['IP']) + logger.debug('%s instance created: %s, %s', CONFIG['SYSTEMS'][system]['MODE'], system, systems[system]) + + reactor.run() \ No newline at end of file diff --git a/hb_confbridge.py b/hb_confbridge.py index a66f865..91c41f2 100755 --- a/hb_confbridge.py +++ b/hb_confbridge.py @@ -18,6 +18,19 @@ # Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA ############################################################################### +''' +This application, in conjuction with it's rule file (hb_confbridge_rules.py) will +work like a "conference bridge". This is similar to what most hams think of as a +reflector. You define conference bridges and any system joined to that conference +bridge will both receive traffic from, and send traffic to any other system +joined to the same conference bridge. It does not provide end-to-end connectivity +as each end system must individually be joined to a conference bridge (a name +you create in the configuraiton file) to pass traffic. + +This program currently only works with group voice calls. +''' + + from __future__ import print_function # Python modules we need diff --git a/hb_config.py b/hb_config.py index 6069bf1..83b76bf 100755 --- a/hb_config.py +++ b/hb_config.py @@ -18,6 +18,14 @@ # Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA ############################################################################### +''' +This module generates the configuration data structure for hblink.py and +assoicated programs that use it. It has been seaparated into a different +module so as to keep hblink.py easeier to navigate. This file only needs +updated if the items in the main configuraiton file (usually hblink.cfg) +change. +''' + import ConfigParser import sys diff --git a/hb_const.py b/hb_const.py index 4c75c78..ab7d92c 100755 --- a/hb_const.py +++ b/hb_const.py @@ -18,6 +18,12 @@ # Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA ############################################################################### +''' +These are contants used by HBlink. Rather than stuff them into the main program +file, any new constants should be placed here. It makes them easier to keep track +of and keeps hblink.py shorter. +''' + from __future__ import print_function __author__ = 'Cortney T. Buffington, N0MJS' diff --git a/hb_log.py b/hb_log.py index c27db61..9260618 100755 --- a/hb_log.py +++ b/hb_log.py @@ -18,6 +18,12 @@ # Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA ############################################################################### +''' +This is the logging configuration for hblink.py. It changes very infrequently, +so keeping in a separate module keeps hblink.py more concise. this file is +likely to never change. +''' + import logging from logging.config import dictConfig diff --git a/hb_router.py b/hb_router.py index eaa780f..269f751 100755 --- a/hb_router.py +++ b/hb_router.py @@ -18,6 +18,17 @@ # Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA ############################################################################### +''' +This is a call/packet router for Homebrew Repeater Protocol and is based on +hblink.py. This is a very, very powerful program, but contains a complex +rule file. It can provide end-to-end activation of routing rules, and as +such, is very different from the "reflector" style of call "bridging" that +most hams are used to. Please see the rules file "hb_routing_rules-SAMPLE.py" +for a more complete explanation of how rules work. + +This program currently only works with group voice calls. +''' + from __future__ import print_function # Python modules we need diff --git a/hblink.py b/hblink.py index 57c9f56..0d09631 100755 --- a/hblink.py +++ b/hblink.py @@ -18,6 +18,15 @@ # Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA ############################################################################### +''' +This program does very little on it's own. It is intended to be used as a module +to build applcaitons on top of the HomeBrew Repeater Protocol. By itself, it +will only act as a client or master for the systems specified in its configuration +file (usually hblink.cfg). It is ALWAYS best practice to ensure that this program +works stand-alone before troubleshooting any applicaitons that use it. It has +sufficient logging to be used standalone as a troubeshooting application. +''' + from __future__ import print_function # Specifig functions from modules we need diff --git a/sub_acl.py b/sub_acl.py index 260f654..30622b2 100644 --- a/sub_acl.py +++ b/sub_acl.py @@ -1,3 +1,11 @@ +''' +This is the Access Control List (ACL) file for limiting call +routing/bridging in various hblink.py-based applications. It +is a VERY simple format. The action may be to PERMIT or DENY +and the ACL itself is a list of subscriber IDs that may be +permitted or denied. +''' + ACL_ACTION = "DENY" # May be PERMIT|DENY ACL = [ 1,2,3,4,5,6,7,8,9,10,100