From 7caa8cc810a06b873db3ac0101fc5be1f5096ccb Mon Sep 17 00:00:00 2001 From: Walter Boring Date: Fri, 28 Aug 2026 23:55:30 -0400 Subject: [PATCH] docs: rewrite README for X API v2, paid account requirement, Forgejo links - Update title and overview for X (formerly Twitter) - Add prominent note that a paid X developer account is required - Add credentials table and write-permission warning - Add Configuration section with correct aprsd.yml structure - Add Usage section with command examples and response message table - Add Contributing section pointing to git.hemna.com - Remove stale GitHub/ReadTheDocs/Codecov badges and links - Remove bearer_token from docs (option was removed) - Update all developer.twitter.com refs to developer.x.com Closes #12 --- README.rst | 194 ++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 132 insertions(+), 62 deletions(-) diff --git a/README.rst b/README.rst index 61c5f4f..891c92a 100644 --- a/README.rst +++ b/README.rst @@ -1,11 +1,7 @@ -Send tweet via Ham RADIO! -========================= +Post to X (formerly Twitter) via Ham Radio APRS! +================================================= -|PyPI| |Status| |Python Version| |License| - -|Read the Docs| |Tests| |Codecov| - -|pre-commit| +|PyPI| |Status| |Python Version| |License| |pre-commit| .. |PyPI| image:: https://img.shields.io/pypi/v/aprsd-twitter-plugin.svg :target: https://pypi.org/project/aprsd-twitter-plugin/ @@ -19,98 +15,172 @@ Send tweet via Ham RADIO! .. |License| image:: https://img.shields.io/pypi/l/aprsd-twitter-plugin :target: https://opensource.org/licenses/MIT :alt: License -.. |Read the Docs| image:: https://img.shields.io/readthedocs/aprsd-twitter-plugin/latest.svg?label=Read%20the%20Docs - :target: https://aprsd-twitter-plugin.readthedocs.io/ - :alt: Read the documentation at https://aprsd-twitter-plugin.readthedocs.io/ -.. |Tests| image:: https://github.com/hemna/aprsd-twitter-plugin/workflows/Tests/badge.svg - :target: https://github.com/hemna/aprsd-twitter-plugin/actions?workflow=Tests - :alt: Tests -.. |Codecov| image:: https://codecov.io/gh/hemna/aprsd-twitter-plugin/branch/main/graph/badge.svg - :target: https://codecov.io/gh/hemna/aprsd-twitter-plugin - :alt: Codecov .. |pre-commit| image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white :target: https://github.com/pre-commit/pre-commit :alt: pre-commit +Overview +-------- + +``aprsd-twitter-plugin`` is an `APRSD `_ +plugin that lets a licensed amateur radio operator post to X (formerly Twitter) +directly from a radio by sending an APRS message. + +Send ``tw Hello from the shack! #hamradio`` over APRS and it appears on X. + +.. note:: + + **A paid X developer account is required.** X ended free API v1.1 write + access in February 2023. You need at least the **Basic** tier on the + `X Developer Portal `_ to + obtain write-capable OAuth 1.0a credentials. Read access (and therefore + read-only bearer tokens) is not sufficient — this plugin posts tweets. + + Features -------- -* Sent a tweet from your personal twitter account! -* to tweet send a message of "t Hello World #aprs #hamradio" +* Post to X from any APRS client — HT, mobile rig, Winlink, APRS.fi, etc. +* Only a configurable callsign (and its SSIDs) is authorised to post. +* Optionally appends ``#aprs #aprsd #hamradio`` and the project URL to every + post. +* Uses the **X API v2** via ``tweepy.Client`` — the only supported API for + write access since 2023. Requirements ------------ -* This plugin requires you have a twitter account and create a developer - account with: -* api key -* api key secret -* access token -* access token secret +* Python 3.9 or later +* `APRSD `_ (installed separately) +* `tweepy `_ >= 4.0 +* A **paid X developer account** with an app that has *read + write* + OAuth 1.0a permissions -Add the following entries to the aprsd.yml file +Credentials needed +~~~~~~~~~~~~~~~~~~ -.. code:: yaml +From the `X Developer Portal → Keys and tokens +`_ for your app: - services: - twitter: - apiKey: - apiKey_secret: - access_token: - access_token_secret: ++------------------------------+----------------------------------------------+ +| Config key | Where to find it | ++==============================+==============================================+ +| ``apiKey`` | *API Key* (Consumer Key) | ++------------------------------+----------------------------------------------+ +| ``apiKey_secret`` | *API Key Secret* (Consumer Secret) | ++------------------------------+----------------------------------------------+ +| ``access_token`` | *Access Token* (generate under Keys/Tokens) | ++------------------------------+----------------------------------------------+ +| ``access_token_secret`` | *Access Token Secret* | ++------------------------------+----------------------------------------------+ + +.. important:: + + Make sure the app's **User authentication settings** are set to + *Read and Write* (not just *Read*). Without write permissions the plugin + will return ``Failed: no write permission``. Installation ------------ -You can install *Send tweet via Ham RADIO!* via pip_ from PyPI_: - .. code:: console $ pip install aprsd-twitter-plugin +Configuration +------------- + +Add an ``aprsd_twitter_plugin`` section to your ``aprsd.yml``: + +.. code:: yaml + + aprsd_twitter_plugin: + # Callsign allowed to post. Any SSID of this callsign is also allowed + # (e.g. WB4BOR-1, WB4BOR-9). + callsign: WB4BOR + + # OAuth 1.0a credentials — obtain from developer.x.com + apiKey: + apiKey_secret: + access_token: + access_token_secret: + + # Set false to suppress automatic hashtag/URL appending (default: true) + add_aprs_hashtag: true + +.. warning:: + + Never commit your credentials to version control. Keep ``aprsd.yml`` + out of git (add it to ``.gitignore``). + + Usage ----- -Please see the `Command-line Reference `_ for details. +From your APRS client send a message to your APRSD station: + +.. code:: + + tw + + # or + twitter + +Examples:: + + tw Hello from the ham shack! Grid DM79 + tw Just worked JA on 20m SSB #hamradio + +With ``add_aprs_hashtag: true`` (default) the plugin automatically appends:: + + #aprs #aprsd #hamradio http://git.hemna.com/hemna/aprsd-twitter-plugin + +Keep your total message under 280 characters to avoid truncation by X. + +**Response messages** + ++------------------------------------------+-----------------------------+ +| Plugin response | Meaning | ++==========================================+=============================+ +| ``Post sent!`` | Success | ++------------------------------------------+-----------------------------+ +| `` not authorized to post!`` | Sender not in allow-list | ++------------------------------------------+-----------------------------+ +| ``Failed: no write permission`` | App lacks write permissions | ++------------------------------------------+-----------------------------+ +| ``Failed to post`` | Other X API error | ++------------------------------------------+-----------------------------+ +| ``Failed to create client`` | Credential/config error | ++------------------------------------------+-----------------------------+ Contributing ------------ -Contributions are very welcome. -To learn more, see the `Contributor Guide`_. +Contributions are welcome! + +* Source: http://git.hemna.com/hemna/aprsd-twitter-plugin +* Issues: http://git.hemna.com/hemna/aprsd-twitter-plugin/issues + +To set up a development environment:: + + git clone ssh://git@git.hemna.com:222/hemna/aprsd-twitter-plugin.git + cd aprsd-twitter-plugin + pip install -e ".[dev]" + pre-commit install + +Run the test suite:: + + pytest tests/ -v License ------- -Distributed under the terms of the `MIT license`_, -*Send tweet via Ham RADIO!* is free and open source software. +Distributed under the terms of the `MIT License`_. - -Issues ------- - -If you encounter any problems, -please `file an issue`_ along with a detailed description. - - -Credits -------- - -This project was generated from `@hemna`_'s `APRSD Plugin Python Cookiecutter`_ template. - -.. _@hemna: https://github.com/hemna -.. _Cookiecutter: https://github.com/audreyr/cookiecutter -.. _MIT license: https://opensource.org/licenses/MIT -.. _PyPI: https://pypi.org/ -.. _APRSD Plugin Python Cookiecutter: https://github.com/hemna/cookiecutter-aprsd-plugin -.. _file an issue: https://github.com/hemna/aprsd-twitter-plugin/issues -.. _pip: https://pip.pypa.io/ -.. github-only -.. _Contributor Guide: CONTRIBUTING.rst -.. _Usage: https://aprsd-twitter-plugin.readthedocs.io/en/latest/usage.html +.. _MIT License: https://opensource.org/licenses/MIT