| Name | adfotg JSON |
| Version |
0.4.0
JSON |
| download |
| home_page | |
| Summary | ADF On-The-Go - convert your RPi Zero to Gotek-ready USB disk |
| upload_time | 2023-12-02 15:04:44 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | MIT License Copyright (c) 2018 - 2023 Robikz <zalewapl@gmail.com> Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
amiga
gotek
raspberry pi
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<img align="left" src="/docs/icon.png">
ADF On-The-Go
=============
**ADF On-The-Go (adfotg)** converts your **Raspberry Pi Zero** into an
USB drive with a web interface. It organises your **ADF** images and
allows you to bundle one or more of them into **virtual USB drives**.
You can swap, download, upload and mount ADFs without ever disconnecting
the USB cable from your **Gotek**, all from any modern web browser.
**ADF On-The-Go (adfotg)** is a HTTP service designed for use in a
**Raspberry Pi Zero**. The RPi must be connected through its USB OTG
port to a **Gotek** Floppy Drive emulator in an **Amiga** computer.
ADF On-The-Go can prepare ADF images from files, split big files into
floppy-sized chunks, or just mount the ADF images directly. It allows to
store bundles of ADF files on their own virtual USB drives and swap
multiple virtual USB drives freely. All of this is controlled through a
website interface, by default hosted on a HTTP port **41364**.
There also is a REST API, if you happen to not like the default UI, but
its current status is **unstable**.
```
----------- Linux ------------ USB --------- IDE ---------
| ADF OTG |------>| RPi Zero |------>| Gotek |---->| Amiga |
----------- ------------ no+5V --------- ---------
```
<img align="left" src="/docs/warning.png">
<img align="right" src="/docs/warning.png">
!!! HARDWARE DAMAGE RISK !!!
============================
**CUT OR BLOCK THE +5V LINE IN THE USB CABLE!**
This line connects the voltage from the Raspberry Pi to Gotek and powers
up your Gotek and your Amiga. This is **undesirable**. When Amiga PSU is
OFF, the Amiga will be put in a strange half-state with LEDs lighting up,
but the computer remaining off. The RPi will also reboot. When Amiga PSU
is ON, the +5V USB line will prevent the Amiga's Power LED from dimming
when Amiga reboots.
**FOR SAFETY MEASURES, CUT OR BLOCK THE +5V LINE!**
<img align="right" width=400 src="/docs/mainpage.jpg">
Security
========
**This is important!**
**There's no network security provided by the app itself!**
It doesn't even put a basic HTTP authentication in place. When you host it
on your device, keep it in a private network without remote access.
This software requires **'root' privileges** to perform certain
operations. While the application will run as a normal user, it will abuse
`sudo` to obtain root privileges when needed. Ensure your RPi user can `sudo`
without password prompt.
Requirements
============
Adfotg supports Raspberry Pi OS 12 (bookworm) since version 0.4.0.
Software:
* Raspberry Pi OS 12 (bookworm) or newer
* Python 3, pipx
* mtools
Hardware:
* Raspberry Pi Zero
* Gotek
* An Amiga
OS:
* `sudo` privileges will be required
Preparing your Raspberry Pi
===========================
**This is mandatory.**
We need to make sure we are using the dwc2 USB driver,
and that `dwc2` and `g_mass_storage` modules are enabled.
If you have a fresh Raspberry Pi OS, it's enough to do:
```
echo dtoverlay=dwc2 | sudo tee -a /boot/config.txt
echo dwc2 | sudo tee -a /etc/modules
echo g_mass_storage | sudo tee -a /etc/modules`
```
Then reboot your RPi.
The above is based on https://gist.github.com/gbaman/50b6cca61dd1c3f88f41
In case of trouble with connecting to Gotek, you may try to
diagnose the USB problems by connecting the RPi to an USB socket
in a PC. When an USB drive image is mounted, the PC should see
the RPi as an USB drive.
Install
=======
This program is designed to be run on a **Raspberry Pi Zero** with the
*Raspberry Pi OS*. Installing the release package on anything else is not
recommended, although will succeed and should be harmless (no warranty).
On your Raspberry Pi:
```
sudo apt update && sudo apt install mtools pipx
sudo PIPX_HOME=/opt/adfotg PIPX_BIN_DIR=/usr/local/bin pipx install adfotg
```
The first time installation may be lengthy (it's only a **Zero**, after all).
Integrating with Raspberry Pi OS
--------------------------------
After `pipx install adfotg` is done, run:
```
sudo adfotg --install
```
This will:
1. Add 'adfotg' system user to Raspberry Pi OS and allow this user a
password-less sudo privilege.
2. Create adfotg's default config file in `/etc/adfotg.conf`.
3. Create adfotg's base directory at `/var/lib/adfotg`.
4. Add `adfotg.service` to systemd; adfotg will start with the system.
Update
------
Make sure you do this logged in as the same OS user that you
used during the installation.
```
sudo PIPX_HOME=/opt/adfotg PIPX_BIN_DIR=/usr/local/bin pipx upgrade adfotg
```
Adfotg needs to be restarted now. If you integrated it with your
*Raspberry Pi OS* (see the section below), then it's sufficient to
do this:
```
sudo systemctl restart adfotg
```
Uninstall
=========
Adfotg needs to be uninstalled manually and this is even more involved
than installing. Depending on how far you've went with installation and
what you wish to keep, you may be skipping some steps.
* First of all, stop the service:
```
sudo systemctl stop adfotg
```
* If you wish to uninstall, and then install adfotg again, do:
```
sudo PIPX_HOME=/opt/adfotg PIPX_BIN_DIR=/usr/local/bin pipx uninstall adfotg
```
This will keep the internal Python setup, your config and your ADF/USB library.
Then proceed as if installing for the first time.
* To remove the internal Python setup, do:
```
sudo rm -rf /opt/adfotg
```
* To uninstall from systemd and to remove the adfotg OS user:
```
sudo rm /usr/local/lib/systemd/system/adfotg.service
sudo systemctl daemon-reload
sudo deluser adfotg
```
* To remove the config:
```
sudo rm /etc/adfotg.conf
```
* To remove your ADF and USB images library:
```
sudo rm -rf /var/lib/adfotg
```
Development
===========
Please see [CONTRIBUTING.md](CONTRIBUTING.md).
Troubleshooting
===============
**Problem:** Gotek perpetually displays `---` when connected to RPi,
even though it works with my usual USB drive.
**Solution:** `---` indicates that you have Cortex firmware installed on
your Gotek. See if you have `SELECTOR.ADF` on your USB drive. If yes,
this ADF must also be placed on every mount image you create in adfotg.
**Problem:** I upgraded to a new version, but there are oddities
happening or I don't see any changes.
**Solution:** There may be two reasons for this. Your browser might've
cached the old version of the site or the adfotg service wasn't
restarted. See the "Update" section in README to learn how to restart
the service and clear your browser cache.
**Problem:** This software ceases to work after the system upgrade.
**Solution:** Sorry, both Raspberry Pi OS and the Python rules for
software distribution and installation tend to change. Reinstalling
adfotg from scratch may help. Other than that, contact me for more
help.
Background
==========
[Gotek](http://www.gotek.in/) is a hardware floppy-drive replacement for
legacy machines. Instead of using failure-prone floppy disks, it allows
to use a USB flash drive with floppy-disk images. Multiple images can
be stored on a single flash drive and Gotek allows by default to choose
between them through buttons located on the case. While Gotek is an
excellent device that eradicates the inconvenience of floppy disks,
it not only doesn't solve the inconvenience of disk swapping but makes
it worse by replacing labeled floppy-disks with incomprehensible
ordinal numbers (from 0 to 999).
[Raspberry Pi Zero](https://www.raspberrypi.org/) is a cheap mini-computer
that can run Linux. It has two major features that are in use in this project:
* WiFi
* USB On-The-Go
While WiFi (or any Ethernet connection) is used here as the access layer
to the ADF On-The-Go software, USB On-The-Go is the real enabler. While
it has many applications, we are only interested in one. It allows to
make the RPi appear to be an USB flash drive - a flash drive which
contents we can fully control and change on-the-fly using Linux command
line tools and which we can program to serve the content we want.
Guide for setting up OTG mode on Raspberry Pi can be found here:
https://gist.github.com/gbaman/50b6cca61dd1c3f88f41
[amitools](https://github.com/cnvogelg/amitools/) contains xdftool,
with which adfotg is capable of manipulating ADF image files to
some extent. Adfotg doesn't depend on amitools, but incorporates
a subset of its source code and installs `adfotg-xdftool` as a separate
tool.
REST API
========
REST API documentation is currently a Work-In-Progress.
adfotg is capable of providing the documentation for itself
in a plain-text format through the `/help` endpoint.
Raw data
{
"_id": null,
"home_page": "",
"name": "adfotg",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "Amiga,Gotek,Raspberry Pi",
"author": "",
"author_email": "Robikz <zalewapl@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/13/e5/094bff14784ad23e30d46fc8803c46ebc362f18ceca6bf5e682412a569c4/adfotg-0.4.0.tar.gz",
"platform": null,
"description": "<img align=\"left\" src=\"/docs/icon.png\">\n\nADF On-The-Go\n=============\n\n**ADF On-The-Go (adfotg)** converts your **Raspberry Pi Zero** into an\nUSB drive with a web interface. It organises your **ADF** images and\nallows you to bundle one or more of them into **virtual USB drives**.\nYou can swap, download, upload and mount ADFs without ever disconnecting\nthe USB cable from your **Gotek**, all from any modern web browser.\n\n**ADF On-The-Go (adfotg)** is a HTTP service designed for use in a\n**Raspberry Pi Zero**. The RPi must be connected through its USB OTG\nport to a **Gotek** Floppy Drive emulator in an **Amiga** computer.\nADF On-The-Go can prepare ADF images from files, split big files into\nfloppy-sized chunks, or just mount the ADF images directly. It allows to\nstore bundles of ADF files on their own virtual USB drives and swap\nmultiple virtual USB drives freely. All of this is controlled through a\nwebsite interface, by default hosted on a HTTP port **41364**.\n\nThere also is a REST API, if you happen to not like the default UI, but\nits current status is **unstable**.\n\n```\n ----------- Linux ------------ USB --------- IDE ---------\n | ADF OTG |------>| RPi Zero |------>| Gotek |---->| Amiga |\n ----------- ------------ no+5V --------- ---------\n```\n\n\n<img align=\"left\" src=\"/docs/warning.png\">\n<img align=\"right\" src=\"/docs/warning.png\">\n\n!!! HARDWARE DAMAGE RISK !!!\n============================\n\n**CUT OR BLOCK THE +5V LINE IN THE USB CABLE!**\n\nThis line connects the voltage from the Raspberry Pi to Gotek and powers\nup your Gotek and your Amiga. This is **undesirable**. When Amiga PSU is\nOFF, the Amiga will be put in a strange half-state with LEDs lighting up,\nbut the computer remaining off. The RPi will also reboot. When Amiga PSU\nis ON, the +5V USB line will prevent the Amiga's Power LED from dimming\nwhen Amiga reboots.\n\n**FOR SAFETY MEASURES, CUT OR BLOCK THE +5V LINE!**\n\n\n<img align=\"right\" width=400 src=\"/docs/mainpage.jpg\">\n\nSecurity\n========\n\n**This is important!**\n**There's no network security provided by the app itself!**\n\nIt doesn't even put a basic HTTP authentication in place. When you host it\non your device, keep it in a private network without remote access.\n\nThis software requires **'root' privileges** to perform certain\noperations. While the application will run as a normal user, it will abuse\n`sudo` to obtain root privileges when needed. Ensure your RPi user can `sudo`\nwithout password prompt.\n\n\nRequirements\n============\n\nAdfotg supports Raspberry Pi OS 12 (bookworm) since version 0.4.0.\n\nSoftware:\n\n* Raspberry Pi OS 12 (bookworm) or newer\n* Python 3, pipx\n* mtools\n\nHardware:\n\n* Raspberry Pi Zero\n* Gotek\n* An Amiga\n\nOS:\n\n* `sudo` privileges will be required\n\n\nPreparing your Raspberry Pi\n===========================\n\n**This is mandatory.**\n\nWe need to make sure we are using the dwc2 USB driver,\nand that `dwc2` and `g_mass_storage` modules are enabled.\n\nIf you have a fresh Raspberry Pi OS, it's enough to do:\n\n```\n echo dtoverlay=dwc2 | sudo tee -a /boot/config.txt\n echo dwc2 | sudo tee -a /etc/modules\n echo g_mass_storage | sudo tee -a /etc/modules`\n```\n\nThen reboot your RPi.\n\nThe above is based on https://gist.github.com/gbaman/50b6cca61dd1c3f88f41\n\nIn case of trouble with connecting to Gotek, you may try to\ndiagnose the USB problems by connecting the RPi to an USB socket\nin a PC. When an USB drive image is mounted, the PC should see\nthe RPi as an USB drive.\n\n\nInstall\n=======\n\nThis program is designed to be run on a **Raspberry Pi Zero** with the\n*Raspberry Pi OS*. Installing the release package on anything else is not\nrecommended, although will succeed and should be harmless (no warranty).\n\nOn your Raspberry Pi:\n\n```\n sudo apt update && sudo apt install mtools pipx\n sudo PIPX_HOME=/opt/adfotg PIPX_BIN_DIR=/usr/local/bin pipx install adfotg\n```\n\nThe first time installation may be lengthy (it's only a **Zero**, after all).\n\n\nIntegrating with Raspberry Pi OS\n--------------------------------\n\nAfter `pipx install adfotg` is done, run:\n\n```\n sudo adfotg --install\n```\n\nThis will:\n\n1. Add 'adfotg' system user to Raspberry Pi OS and allow this user a\n password-less sudo privilege.\n2. Create adfotg's default config file in `/etc/adfotg.conf`.\n3. Create adfotg's base directory at `/var/lib/adfotg`.\n4. Add `adfotg.service` to systemd; adfotg will start with the system.\n\n\nUpdate\n------\n\nMake sure you do this logged in as the same OS user that you\nused during the installation.\n\n```\n sudo PIPX_HOME=/opt/adfotg PIPX_BIN_DIR=/usr/local/bin pipx upgrade adfotg\n```\n\nAdfotg needs to be restarted now. If you integrated it with your\n*Raspberry Pi OS* (see the section below), then it's sufficient to\ndo this:\n\n```\n sudo systemctl restart adfotg\n```\n\n\nUninstall\n=========\n\nAdfotg needs to be uninstalled manually and this is even more involved\nthan installing. Depending on how far you've went with installation and\nwhat you wish to keep, you may be skipping some steps.\n\n* First of all, stop the service:\n\n```\n sudo systemctl stop adfotg\n```\n\n* If you wish to uninstall, and then install adfotg again, do:\n\n```\n sudo PIPX_HOME=/opt/adfotg PIPX_BIN_DIR=/usr/local/bin pipx uninstall adfotg\n```\n\nThis will keep the internal Python setup, your config and your ADF/USB library.\nThen proceed as if installing for the first time.\n\n* To remove the internal Python setup, do:\n\n```\n sudo rm -rf /opt/adfotg\n```\n\n* To uninstall from systemd and to remove the adfotg OS user:\n\n```\n sudo rm /usr/local/lib/systemd/system/adfotg.service\n sudo systemctl daemon-reload\n sudo deluser adfotg\n```\n\n* To remove the config:\n\n```\n sudo rm /etc/adfotg.conf\n```\n\n* To remove your ADF and USB images library:\n\n```\n sudo rm -rf /var/lib/adfotg\n```\n\n\nDevelopment\n===========\n\nPlease see [CONTRIBUTING.md](CONTRIBUTING.md).\n\n\nTroubleshooting\n===============\n\n**Problem:** Gotek perpetually displays `---` when connected to RPi,\neven though it works with my usual USB drive.\n\n**Solution:** `---` indicates that you have Cortex firmware installed on\nyour Gotek. See if you have `SELECTOR.ADF` on your USB drive. If yes,\nthis ADF must also be placed on every mount image you create in adfotg.\n\n\n**Problem:** I upgraded to a new version, but there are oddities\nhappening or I don't see any changes.\n\n**Solution:** There may be two reasons for this. Your browser might've\ncached the old version of the site or the adfotg service wasn't\nrestarted. See the \"Update\" section in README to learn how to restart\nthe service and clear your browser cache.\n\n\n**Problem:** This software ceases to work after the system upgrade.\n\n**Solution:** Sorry, both Raspberry Pi OS and the Python rules for\nsoftware distribution and installation tend to change. Reinstalling\nadfotg from scratch may help. Other than that, contact me for more\nhelp.\n\n\nBackground\n==========\n\n[Gotek](http://www.gotek.in/) is a hardware floppy-drive replacement for\nlegacy machines. Instead of using failure-prone floppy disks, it allows\nto use a USB flash drive with floppy-disk images. Multiple images can\nbe stored on a single flash drive and Gotek allows by default to choose\nbetween them through buttons located on the case. While Gotek is an\nexcellent device that eradicates the inconvenience of floppy disks,\nit not only doesn't solve the inconvenience of disk swapping but makes\nit worse by replacing labeled floppy-disks with incomprehensible\nordinal numbers (from 0 to 999).\n\n\n[Raspberry Pi Zero](https://www.raspberrypi.org/) is a cheap mini-computer\nthat can run Linux. It has two major features that are in use in this project:\n\n* WiFi\n* USB On-The-Go\n\nWhile WiFi (or any Ethernet connection) is used here as the access layer\nto the ADF On-The-Go software, USB On-The-Go is the real enabler. While\nit has many applications, we are only interested in one. It allows to\nmake the RPi appear to be an USB flash drive - a flash drive which\ncontents we can fully control and change on-the-fly using Linux command\nline tools and which we can program to serve the content we want.\n\nGuide for setting up OTG mode on Raspberry Pi can be found here:\nhttps://gist.github.com/gbaman/50b6cca61dd1c3f88f41\n\n\n[amitools](https://github.com/cnvogelg/amitools/) contains xdftool,\nwith which adfotg is capable of manipulating ADF image files to\nsome extent. Adfotg doesn't depend on amitools, but incorporates\na subset of its source code and installs `adfotg-xdftool` as a separate\ntool.\n\n\nREST API\n========\n\nREST API documentation is currently a Work-In-Progress.\nadfotg is capable of providing the documentation for itself\nin a plain-text format through the `/help` endpoint.\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2018 - 2023 Robikz <zalewapl@gmail.com> Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "ADF On-The-Go - convert your RPi Zero to Gotek-ready USB disk",
"version": "0.4.0",
"project_urls": {
"Homepage": "https://github.com/zalewa/adfotg"
},
"split_keywords": [
"amiga",
"gotek",
"raspberry pi"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9da0697b3e4e4d87c30b0529bd69b8ca5bf23921fa209f607e6a7d699e7855b0",
"md5": "9db5db608f8d55a8e4cc1765cae97019",
"sha256": "469d3247861c3dd5ee68fe23637050c06d7c5702d1cec9399e6be9fbe9e8a401"
},
"downloads": -1,
"filename": "adfotg-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9db5db608f8d55a8e4cc1765cae97019",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 845068,
"upload_time": "2023-12-02T15:04:41",
"upload_time_iso_8601": "2023-12-02T15:04:41.631329Z",
"url": "https://files.pythonhosted.org/packages/9d/a0/697b3e4e4d87c30b0529bd69b8ca5bf23921fa209f607e6a7d699e7855b0/adfotg-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "13e5094bff14784ad23e30d46fc8803c46ebc362f18ceca6bf5e682412a569c4",
"md5": "16854912b4ddc5e378e0ca3f85bb8561",
"sha256": "62b85ff1c22efb0fcba50e08a0a790d8ce5ce6b548035a2c1cbd9e719f88bbe9"
},
"downloads": -1,
"filename": "adfotg-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "16854912b4ddc5e378e0ca3f85bb8561",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 1154234,
"upload_time": "2023-12-02T15:04:44",
"upload_time_iso_8601": "2023-12-02T15:04:44.384567Z",
"url": "https://files.pythonhosted.org/packages/13/e5/094bff14784ad23e30d46fc8803c46ebc362f18ceca6bf5e682412a569c4/adfotg-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-02 15:04:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "zalewa",
"github_project": "adfotg",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "adfotg"
}
