search

mycodeplug / dzcb

DMR Zone Channel Builder. See https://github.com/mycodeplug/example-codeplug to customize.
MIT License
12 stars 11 forks source link

readme

dzcb

DMR Zone Channel Builder

Overview Video

See Releases for Default Codeplugs

Github Actions

For more information on generating customized codeplugs in the cloud without installing any software, see WALKTHROUGH.

The walkthrough uses mycodeplug/example-codeplug [input files]

Output Formats

Farnsworth JSON

For import into editcp, with theoretical support for:

Use --farnsworth-template-json to specify an exported codeplug to use as the template for settings and radio capabilities.

dzcb includes basic template files for MD380/390 and MD-UV380/390.

Generated JSON files will be written to the editcp subdir of the output directory.

OpenRTX/dmrconfig

For import into dmrconfig 1.1 utility with theoretical support for:

Use --dmrconfig-template to specify an exported codeplug config to use as a template for radio type, messages, DMR ID, and startup text. The dmrconfig subdir of the output directory will contain a dmrconfig config per template specified.

Anytone CPS

For import into the official Anytone CPS (windows-only).

dzcb generates Channels.CSV, Talkgroups.CSV, ScanList.CSV, and Zone.CSV in the anytone subdir of the output directory.

Versions Supported

(links fetched 2021/01/24)

GB3GF OpenGD77 CSV

For import into GB3GF CSV tool. Currently only supporting OpenGD77 target. Tool is "windows-only" but runs decently under wine.

If --gb3gf is specified, the gb3gf/opengd77 subdir of the output directory will contain the 4 CSV files used by the program:

Note: these files are actually semicolon separated.

Input Format

K7ABD style

A directory of inter-related CSV files describing the common settings needed to program all radios. This is a common format used by K7ABD's original anytone-config-builder and N7EKB's cps-import-builder.

An arbitrary number of files and folders will be combined. At this time duplicate zone names in different files may be problematic. Keep zone names unique. Particularly be wary of trucated names.

Data Sources

PNWdigital.net

Before using this network, please read the quick start

When building a codeplug with the --pnwdigital switch, data is downloaded from PNWDigital.net/files/acb. The files are updated regularly from the cBridge, so there could be test data or repeaters that are not yet active.

The data is cached by dzcb.pnwdigital

SeattleDMR

Before using these repeaters, please read the website

When building a codeplug with the --seattledmr switch, data is downloaded from seattledmr.org/ConfigBuilder/Digital-Repeaters-Seattle-addon.csv and cleaned up a bit in dzcb.seattledmr

Repeaterbook Proximity

Download live analog Repeaterbook data within distance of point of interest.

--repeaterbook-proximity-csv references a csv file with the fields:

See example: src/dzcb/data/repeaterbook_proximity_zones.csv

The fields after Band are optional and correspond directly to the field names and values in the Repeaterbook API (see examples).

--repeaterbook-state is a space-separated list of US states or Canadian provinces that should be included in the proximity search. Including more states will increase the time required to generate the codeplug.

Repeaterbook API data is downloaded and cached in a user and platform-specific cache directory. Data will be refreshed if it is older than 12 hours. When downloading from Repeaterbook, a delay of 30 seconds is introduced between requests to reduce load on the repeaterbook servers.

Please respect their servers and submit changes requests to repeaterbook directly.

See dzcb.repeaterbook.

Example Format

Zone Name,Lat,Long,Distance,Unit,Band(2m;1.25m;70cm),Use,Operational Status
Longview WA 35mi,46.13819885,-122.93800354,35,miles,2m;70cm,OPEN,On-air
Longview WA VHF 35mi,46.13819885,-122.93800354,35,miles,2m,open,On-air
Longview WA UHF 35mi,46.13819885,-122.93800354,35,miles,70cm,OPEN,On-Air

(it's easy to search on repeaterbook and copy the info from the URL!)

Simplex, GMRS, etc

Some common Digital and Analog simplex frequencies, and GMRS/FRS and MURS channels are included if --default-k7abd is specified.

Customization

The channels, zones, and contacts present and the ordering of such in the final generated codeplug is controlled by one or more CSV files passed as parameters.

The column headers correspond to the codeplug objects (zones, contacts, channels, etc) and may appear in any order or be omitted (if no change is requested to that type of codeplug object).

The names used in include, exclude, and order are python regular expressions that match from the beginning of the object name. They are prefix match by default. To opt-out of prefix match, add a $ at the end. All regular expression special characters should be escaped (\).

--include

If the CSV file is passed as a --include parameter, then any objects not explicitly mentioned in the file will be removed.

--exclude

If the CSV file is passed as an --exclude parameter, then any objects mentioned will be removed.

See example: codeplug/default-tyt-md380/exclude.csv (for radios with lower channel/zone capacity)

--order

Alphabetic sorting by filename is used when initially building the zones and channels from K7ABD input files. No implicit sorting by object name occurs.

Any remaining objects are sorted according to the order specified in the file passed to --order. Similarly, a file may be specified as --reverse-order which will sort in reverse, starting from the end of the list.

See example: codeplug/default/order.csv

--replacements

The replacements CSV column headers are like object_pattern,object_repl and correspond exactly to the arguments passed to python's re.sub. Similar to the ordering csv, object would refer to zones, contacts, channels, etc.

The replacements will be applied to the name of each object of the given type in the listed order. Subsequent patterns will affect previous replacements. Unlike the previous group, these regular expressions are case sensitive, support capturing groups, and indexed replacement.

See example: codeplug/default/replacements.csv

--repeaterbook-name-format

Python format string used to generate channel names from repeaterbook.

The format string will be passed the Repeaterbook API response dictionary for the repeater, so all valid fields are usable in the format string.

The default name format is: "{Callsign} {Nearest City} {Landmark}"

Bonus: Trim the Contact List

Download the usersDB.bin with Farnsworth editcp.

python -m dzcb.contact_trim \
    < "~/.cache/codeplug/Codeplug Editor/usersDB.bin" \
    > "~/.cache/codeplug/Codeplug Editor/usersDB-trimmed.bin"

Basic Usage

Installation

pip install dzcb

Example

Download live pnwdigital and seattledmr networks and generate a dmrconfig style codeplug in /tmp/my-codeplug with local simplex zones included.

python -m dzcb \
    --pnwdigital \
    --seattledmr \
    --default-k7abd \
    --dmrconfig -- /tmp/my-codeplug

Docker Container

A docker container for dzcb can be built and run as follows:

# Build container
tools/build_docker.sh

# Run dzcb
docker run --rm -ti \
      -v /tmp/my-codeplug:/my-codeplug \
      dzcb \
      --pnwdigital \
      --seattledmr \
      --default-k7abd \
      --dmrconfig \
      -- \
      /my-codeplug

Complex Usage

See WALKTHROUGH for a step-by-step guide to getting started with your own customized codeplug build. (The walkthrough uses mycodeplug/example-codeplug)

CLI

$ python -m dzcb --help
usage: python -m dzcb [-h] [--pnwdigital] [--seattledmr] [--default-k7abd] [--k7abd [DIR [DIR ...]]]
                   [--repeaterbook-proximity-csv [CSV [CSV ...]]] [--repeaterbook-state [STATE [STATE ...]]]
                   [--repeaterbook-name-format REPEATERBOOK_NAME_FORMAT] [--scanlists-json JSON] [--include [CSV [CSV ...]]]
                   [--exclude [CSV [CSV ...]]] [--order [CSV [CSV ...]]] [--reverse-order [CSV [CSV ...]]]
                   [--replacements [CSV [CSV ...]]] [--anytone [RADIO [RADIO ...]]] [--dmrconfig-template [CONF [CONF ...]]]
                   [--farnsworth-template-json [JSON [JSON ...]]] [--gb3gf [RADIO [RADIO ...]]]
                   outdir

dzcb: DMR Zone Channel Builder

positional arguments:
  outdir                Write codeplug files to this directory

optional arguments:
  -h, --help            show this help message and exit
  --pnwdigital          Fetch the latest pnwdigital K7ABD input files
  --seattledmr          Fetch the latest seattledmr K7ABD input files
  --default-k7abd       Include bundled K7ABD input files (simplex + unlicensed)
  --k7abd [DIR [DIR ...]]
                        Specify one or more local directories containing K7ABD CSV files
  --repeaterbook-proximity-csv [CSV [CSV ...]]
                        Fetch repeaters within X distance of POIs defined in a CSV file
  --repeaterbook-state [STATE [STATE ...]]
                        Download repeaters from the given state(s). Default: 'Washington' 'Oregon'
  --repeaterbook-name-format REPEATERBOOK_NAME_FORMAT
                        Python format string used to generate channel names from repeaterbook. See Repeaterbook API response
                        for usable field names. Default: '{Callsign} {Nearest City} {Landmark}'
  --scanlists-json JSON
                        JSON dict mapping scanlist name to list of channel names.
  --include [CSV [CSV ...]]
                        Specify one or more CSV files with object names to include
  --exclude [CSV [CSV ...]]
                        Specify one or more CSV files with object names to exclude
  --order [CSV [CSV ...]]
                        Specify one or more CSV files with object order by name
  --reverse-order [CSV [CSV ...]]
                        Specify one or more CSV files with object order by name (reverse)
  --replacements [CSV [CSV ...]]
                        Specify one or more CSV files with object name replacements
  --anytone [RADIO [RADIO ...]]
                        Generate Anytone CPS CSV files in the 'anytone' subdir for the given radio and CPS versions. If no
                        RADIO+CPS versions are provided, use default set: (578_1_11 868_1_39 878_1_21)
  --dmrconfig-template [CONF [CONF ...]], --dmrconfig [CONF [CONF ...]]
                        Generate dmrconfig conf files in the 'dmrconfig' subdir based on the given template conf files. If no
                        templates are provided, default templates will be used.
  --farnsworth-template-json [JSON [JSON ...]], --editcp [JSON [JSON ...]]
                        Generate Farnsworth editcp JSON format codeplugs in the 'editcp' subdir based on the given template
                        json files. If no templates are provided, default templates will be used.
  --gb3gf [RADIO [RADIO ...]]
                        Generate GB3GF CSV files in the 'gb3gf' subdir for the given radio types. If no radios are provided,
                        use default: (opengd77)

Python API

dzcb exposes a python API that is identical to the command line interface which can be extended to further customize the generation process without having to directly patch dzcb.

The documentation should improve as the project matures, but for now, see generate.py for a real example and dzcb.recipe.CodeplugRecipe for the implementation details.

Development Usage

Installation

pip install -e ./dzcb

Development Docker Container

A docker container for dzcb development can be built and run as follows:

# Build container
tools/build_docker_dev.sh

# Run dzcb
docker run --rm -ti \
      -v /tmp/my-codeplug:/my-codeplug \
      -v .:/app/dzcb \
      dzcb:dev

Bugs?

Please submit the entire output directory including log files when submitting issues.