From fd9239c2bb131c1005555852377fb46581b29452 Mon Sep 17 00:00:00 2001
From: poslop <poslop@archfox.org>
Date: Mon, 2 Feb 2026 14:55:05 -0600
Subject: [PATCH] reamde

---
 readme.md | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)
 create mode 100644 readme.md

diff --git a/readme.md b/readme.md
new file mode 100644
index 0000000..742e9a4
--- /dev/null
+++ b/readme.md
@@ -0,0 +1,59 @@
+## Gen PC Sidecar Script
+The files are stored typically inside of `/var/lib/asterisk/PC-Contact-Sync` and the scripts should be run every 6 hours by a cron job.
+
+<br>
+
+## Quickstart
+#### Config Fields
+`config.json` has several fields. The config file needs to  be next to the script in order to be read.
+
+<div style="border-left: 6px solid #FFA500; padding: 10px;">
+<strong>⚠️ Warning:</strong> Make sure the config follows proper json syntax.
+</div>
+<br>
+
+```
+target_extensions
+list_filter_type
+extension_filter_list
+blacklisted_terms
+prepend_extensions
+```
+
+1. Add the phones that need a config pushed out for to the `target_extensions` list.
+2. Add the type of filter you want to use to filter out extensions from the contact list to `list_filter_type`.
+3. Add Extensions you want either black/white listed to the `extension_filter_list`.
+4. Add words that are in contacts you want removed to `blacklisted_terms`.
+5. Add extra contacts you want added to the phones in `prepend_extensions`.
+
+<br>
+
+## Process Walkthrough
+
+#### 1. Pull Contact List
+Initially the script formats together a contact list to be pushed to the phones. This php script will pull every contact from asterisk database which contains a **name** and **extension**.
+
+#### 2. Contact List Formatting
+The script will now filter the contact list before writing to the phones. It has 3 processes to format it:
+ 
+ 1. Filter extensions by black/white list
+ 2. Remove blacklisted terms
+ 3. Prepend a set of configured contacts listed
+
+The filter list will apply either a black/white list to the `extension_filter_list`.  If it is a white list `extension_filter_list` is kept and anything not in it is removed.  If it is a blacklist anything inside of `extension_filter_list` is removed.
+
+The script will remove any contact name that has words contained inside of `blacklisted_terms`.  
+
+Finally contacts specified in `prepend_extensions` are added to the beginning of the contact list.
+
+#### 3. Write to phones
+Polycom phones read their extension list to display on the phone from a file in `/tftboot` that is served by PBXact.  The phone looks for settings including its contact list in `/tftboot/phone_mac_address-features.cfg` replacing mac_address with the actual mac of the phone without any : in the number. The default if it cant find its mac is to use the file with 0s.
+
+##### Example:
+```
+/tftboot/000000000-features.cfg
+```
+
+The script will go down the list and read the .cfg for each phone in `target_extensions` and write in the contact list that was created earlier. It wites to a config file that matches the extensions mac address.
+
+Phones might need to be told to reconfigure to pull the updated cfg.
-- 
2.49.1