Merge pull request #74 from masenf/beta-docs

Beta Documentation

Author: masenf

README.md

@@ -287,8 +287,8 @@ codeplug in `/tmp/my-codeplug` with local simplex zones included.
 python -m dzcb \
     --pnwdigital \
     --seattledmr \
-    --default-k7abd /tmp/my-codeplug
-    --dmrconfig
+    --default-k7abd \
+    --dmrconfig -- /tmp/my-codeplug
 ```
 
 # Complex Usage

doc/BETA.md

@@ -0,0 +1,82 @@
+# `dzcb` 0.3 Public Beta
+
+Thank you for your interest in beta testing [`dzcb`](https://github.com/mycodeplug/dzcb).
+Please remember that this project is developed by a single person in spare time only.
+
+See [HISTORY](./HISTORY.md) for motivation, criticisms, and feature development
+backstory.
+
+## Scope of Current Testing
+
+I have personally tested dzcb with the following radios:
+
+  * TYT MD-UV380 (editcp JSON and dmrconfig)
+  * Anytone D878UV (CSV and dmrconfig)
+  * Radioddity GD-77 (Stock firmware and dmrconfig)
+
+I test the pnwdigital, seattledmr, custom k7abd, and repeaterbook sources.
+
+Additionally, I have tested the exclude, order, and replacements CSV modifications
+as well as custom scanlists.
+
+## Testing Needed
+
+Testing is needed for the following popular radios:
+   
+  * Anytone 578
+  * TYT MD380 - UHF or VHF only
+  * BTECH DMR-6x2
+  * Baofeng RD-5R
+
+Testing is needed for the `include` CSV and repeaterbook name format.
+
+**I would also like feedback on general usability and quality of documentation.**
+
+## Where to Start
+
+At least scan through the [`dzcb` README](/README.md) to get an idea
+of what features are available and what formats are supported.
+
+Look at
+[`mycodeplug/example-codeplug`](https://github.com/mycodeplug/example-codeplug)
+for a fully working example with sample CSV files and scripts to generate the
+codeplug.
+
+If you're brand new to codeplug generators and github, please see the
+[WALKTHROUGH](/doc/WALKTHROUGH.md) for a step-by-step guide to building a
+codeplug online using github actions.
+
+If you already use K7ABD's `anytone-config-builder`, then you likely already have
+files that will work with `dzcb`.
+
+For example, to install dzcb and build existing ACB CSV files into dmrconfig codeplug
+files (requires python 3.6+):
+
+```
+pip install dzcb~=0.3.1
+python -m dzcb --k7abd /path/to/existing/acb_csv --dmrconfig -- /tmp/new-codeplug
+```
+
+## Known Issues
+
+* Invalid CSV input may cause the program to exit without indicating which file was
+  problematic. This will be fixed in a later release. See [issue #73](https://github.com/mycodeplug/dzcb/issues/73)
+
+# Support
+
+Unfortunately I'm not able to provide personalized support for connecting your
+radio, installing drivers, python, or CPS software, or any general DMR questions.
+
+## Feedback and Feature Requests
+
+Please file an [issue](https://github.com/mycodeplug/dzcb/issues/new) or email
+`[email protected]` with any usability feedback or feature requests. Be sure to
+include detailed descriptions, example usage, and sample files and command
+lines that will help me understand the request.
+
+## Bugs
+
+If you have discovered a bug, please file an
+[issue](https://github.com/mycodeplug/dzcb/issues/new) in this repository,
+including the full codeplug output directory and log file, the full error
+message, operating system and python version, and any other relevant details.

doc/HISTORY.md

@@ -0,0 +1,105 @@
+# `dzcb` History
+
+`dzcb` is written by Masen Furer KF7HVM <[email protected]>.
+
+## Motivation
+
+`dzcb` development began in late October 2020 in response to the lack of
+existing tools for creating a TYT MD-UV380 codeplug from a matrix of repeater
+frequencies and talkgroups.
+
+The [PNWDigital](http://pnwdigital.net) group publishes information on its
+repeater system in standard format CSV files (K7ABD format) which are generated
+directly from the network cBridges, and I wanted to use these files to directly
+generate a cross-platform compatible codeplug targeting the TYT MD-UV380, using
+[editcp](https://www.farnsworth.org/dale/codeplug/editcp/).
+
+And thus `dzcb` was born.
+
+## Criticism
+
+> Why did you need to write 3800 lines of code over 6 months to do what I could
+> do with an afternoon and a spreadsheet program?
+
+Well, I _personally_ don't like editing codeplugs by hand, neither in a CPS or
+in a spreadsheet.
+
+The CPS experience is hit or miss depending on what radio you have and
+any work done in a CPS to edit a codeplug will generally not be applicable
+to other radio types. Vendor CPS packages are "different enough" from each
+other, often buggy, and only support Windows.
+
+The spreadsheet experience can be slightly better (at least you're using find/replace
+instead of clicking through lists and buggy forms). However, the problem
+with most CSV import formats is _they key on object name_, so renaming objects
+can be problematic, and needs to occur in multiple places (and possibly,
+multiple separate files).
+
+Finally, neither CPS nor CSV solve the problem of expanding a list of talkgroups
+across a single repeater, and the existing tools only support Anytone CPS format.
+
+_(Please email [email protected] with further criticism and I will respond publicly here)_
+
+
+## Feature Development
+
+### Repeaterbook
+
+Since [repeaterbook](http://repeaterbook.com) is the primary source of analog
+repeater information in the region, I added support for automatically
+downloading up-to-date repeater records and formatting those in the same K7ABD
+analog format.
+
+Rather than download and assemble the zone/channel CSV by hand (copy/paste from
+RB), it made more sense to define a new CSV file with points of interest,
+distances, and desired bands to create the channels entries fresh whenever the
+codeplug is built.
+
+When repeater information is incorrect in the codeplug, it can be updated on
+Repeaterbook to benefit everyone.
+
+### More Output Formats
+
+Along the way, additional output formats were added based on recommendation
+or needs.
+
+#### GB3GF OpenGD77
+
+This format is the only good way to represent an OpenGD77 codeplug in CSV format
+and is a defacto standard in the opengd77 world.
+
+Because the opengd77 firmware handles static talkgroups much differently than
+other common radios, it required a significant restructuring of the internal
+representation of the codeplug. Ultimately this architectural change made it
+easier to represent a single channel with multiple talkgroups which could later
+be expanded into multiple channels.
+
+#### Anytone CSV
+
+Anytone radios are popular and many people prefer to use the official CPS despite
+the fact that it only runs on windows. Support for Anytone CPS import format was
+added to achieve parity with existing codeplug generators. The implementation is
+flexible such that future CPS format changes can be easily accomodated.
+
+#### dmrconfig
+
+On the advice of Dave W7NCX, support for the cross platform cli tool
+[`dmrconfig`](https://github.com/OpenRTX/dmrconfig) textual codeplug
+format was added.
+
+### Advanced Filtering
+
+In response to user feedback, a new CSV format was created to allow an end user
+to customize names, include/exclude objects, and reorder zones, contacts, and
+channels within a codeplug.
+
+These modifications are performed against the original source files so there is
+no "manual" effort when the upstream data source updates the talkgroup deck,
+color code or frequency. The name and ordering will be applied to the updated
+channels as before.
+
+### `example-codeplug`
+
+An [example codeplug](https://github.com/mycodeplug/example-codeplug) and
+additional documentation was added to facilitate use by others in the
+community.

doc/README.md

@@ -1,3 +1,8 @@
 # dzcb
 
 Docs and supporting files
+
+* [WALKTHROUGH](./WALKTHROUGH.md) - step-by-step guide for building codeplug
+* [BETA](./BETA.md) - beta testing guidelines
+  with github actions
+* [HISTORY](./HISTORY.md) - motivation, criticism, and feature development history

setup.py

@@ -20,7 +20,7 @@ def read(*parts):
     long_description_content_type='text/markdown',
     author='Masen Furer',
     author_email='[email protected]',
-    url='https://github.com/masenf/dzcb',
+    url='https://github.com/mycodeplug/dzcb',
     package_dir={"": 'src'},
     package_data={'dzcb': ['data/*.json', 'data/*.csv', 'data/k7abd/*.csv', 'data/farnsworth/*.json', 'data/dmrconfig/*.conf']},
     packages=setuptools.find_packages('src'),

src/dzcb/k7abd.py

@@ -149,20 +149,20 @@ def Analog_from_csv(analog_repeaters_csv):
     zones = {}
     csvr = csv.DictReader(analog_repeaters_csv)
     for r in csvr:
-        zname = r[ZONE]
-        zname, found, code = zname.partition(";")
-        name = r[CHANNEL_NAME]
-        frequency = float(r[RX_FREQ])
-        offset = round(float(r[TX_FREQ]) - frequency, 1)
-        power = r[POWER]
-        bandwidth = r[BANDWIDTH].rstrip("K")
-        tone_encode = (
-            r[CTCSS_ENCODE] if r[CTCSS_ENCODE].lower() not in ("off", "") else None
-        )
-        tone_decode = (
-            r[CTCSS_DECODE] if r[CTCSS_DECODE].lower() not in ("off", "") else None
-        )
         try:
+            zname = r[ZONE]
+            zname, found, code = zname.partition(";")
+            name = r[CHANNEL_NAME]
+            frequency = float(r[RX_FREQ])
+            offset = round(float(r[TX_FREQ]) - frequency, 1)
+            power = r[POWER]
+            bandwidth = r[BANDWIDTH].rstrip("K")
+            tone_encode = (
+                r[CTCSS_ENCODE] if r[CTCSS_ENCODE].lower() not in ("off", "") else None
+            )
+            tone_decode = (
+                r[CTCSS_DECODE] if r[CTCSS_DECODE].lower() not in ("off", "") else None
+            )
             zones.setdefault(zname, []).append(
                 AnalogChannel(
                     name=name,