Metadata-Version: 2.1
Name: little-atf-programmer
Version: 2024.1012
Summary: Little ATF150x Programmer Board utility programs
Author-email: The Really Old-School Company Limited <info@rosco-m68k.com>
License: Copyright (c) 2024 The Really Old-School Company Limited
        
        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.
        
        
        ##############################
        ##############################
        
        
        Portions Copyright (C) 2019-2020 whitequark@whitequark.org
        
        Permission to use, copy, modify, and/or distribute this software for
        any purpose with or without fee is hereby granted.
        
        THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
        WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
        MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
        ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
        WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
        AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
        OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
        
        
        ##############################
        ##############################
        
        
        Portions Copyright (c) 2015 Marcelo Roberto Jimenez <marcelo.jimenez (at) gmail (dot) com>
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
           1. Redistributions of source code must retain the above copyright notice,
              this list of conditions and the following disclaimer.
        
           2. Redistributions in binary form must reproduce the above copyright
              notice, this list of conditions and the following disclaimer in the
              documentation and/or other materials provided with the distribution.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
        
        
        ##############################
        ##############################
        
        
        Portions Copyright 2008, SoftPLC Corporation  http://softplc.com
        Dick Hollenbeck dick@softplc.com
        
        
        This program is free software; you can redistribute it and/or
        modify it under the terms of the GNU General Public License
        as published by the Free Software Foundation; either version 2
        of the License, or (at your option) any later version.
        
        This program is distributed in the hope that it will be useful,
        but WITHOUT ANY WARRANTY; without even the implied warranty of
        MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
        GNU General Public License for more details.
        
        You should have received a copy of the GNU General Public License
        along with this program; if not, you may find one here:
        http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
        or you may search the http://www.gnu.org website for the version 2 license,
        or you may write to the Free Software Foundation, Inc.,
        51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA
        
        
        
Project-URL: Homepage, https://github.com/roscopeco/atfprog-tools
Keywords: cpld,atf1502,atf1504,atf1508,logic,programmer
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: pyserial==3.5
Requires-Dist: pyparsing==3.1.2
Requires-Dist: bitarray==2.9.2
Requires-Dist: tabulate==0.9.0
Requires-Dist: progress==1.6
Requires-Dist: tqdm==4.66.2
Provides-Extra: dev
Requires-Dist: black; extra == "dev"
Requires-Dist: bumpver; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: pip-tools; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: sure; extra == "dev"
Requires-Dist: httpretty; extra == "dev"

# Little ATF150x Programmer Board
## Software utilities

### What

This repository contains the official standard programmer software and utilities 
for the Little ATF150x Programmer Board.

![Picture of The Little ATF150x Programmer](https://github.com/roscopeco/atfprog-tools/raw/main/images/board.jpeg)

This is a plug-and-play USB-connected programmer and breakout board for
Atmel (Microchip) ATF150{2,4,8} CPLDs, featuring:

* Support for JED, SVF or XSVF files
* Support for both PLCC44 and 84 packages on-board
* Ability to drive ICSP via the JTAG headers (single-device only - chains **not** currently supported)
* Ability to erase JTAG-locked and secured devices

The board is currently in community testing, and will be available soon 
on the [rosco_m68k store](https://store.rosco-m68k.com) 🥳

### Software Installation

Prerequisites:

* Recent macOS, Linux or Windows operating system
* Working Python (3.9+) installation
  * Recent macOS and Linux will likely have this by default
  * If not, it can be installed with your package manager
  * Windows users can download from https://www.python.org/downloads/windows
  * `python` and `pip` should be in your `PATH` for easiest installation experience

> **Note**: on some systems, your `python` may instead be named `python3`, with `pip`
> being similarly named `pip3`. As long as Python is version 3.9 or higher 
> (as reported by `python3 --version`) it should work just fine.

#### Latest release

With a Python environment that meets these requirements, installation
is as simple as:

```shell
pip install little-atf-programmer
```

> **Note**: on Windows, when installing you may receive a message from pip
> warning that the installed binaries are not in your `PATH`. If you see this,
> for easier installation you may wish to add the directory in the warning
> to your `PATH` by editing in
> `Control Panel / System / Advanced / Environment Variables.`

#### From source

Developers and project collaborators may wish to install from source. 

To do this, clone the project from GitHub (or grab a source tarball).

Then either run `python src/atfu.py` or install with pip if you like:

```shell
pip install .
```

If you're hacking on the code, you'll probably want to install it `--editable`.

### Usage

#### General arguments

General command line arguments look like this:

```
atfu [-h] [--version] [-q] [-v] [-t] {program,erase,check,programmer} ...

Little ATF150x Programmer Board Utility

positional arguments:
  {program,erase,check,programmer}
    program             Program an ATF150x device
    erase               Erase an ATF150x device
    check               Check if an ATF150x device is blank
    programmer          Little ATF150x Programmer Board device functions

optional arguments:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
  -q, --quiet           Silence almost all output
  -v, --verbose         Allow additional output
  -t, --trace           Enable debugging output (can be noisy!)
```

#### Program mode

This mode is used to program JEDEC, SVF or XSVF files to an ATF150x device.

By default, the first detected programmer will be used. This can be changed
with the `-p` option.

If you have problems programming, try erasing first with the `-e` option,
or force-erasing with the `-f` option, which can be useful when you have a
JTAG-locked or secured device.

```
atfu program [-h] [-e] [-f] [-d {ATF1502,ATF1504,ATF1508}] [-p PROGRAMMER] filename [filename ...]

positional arguments:
  filename              .jed, .svf or .xsvf file(s) to program

options:
  -h, --help            show this help message and exit
  -e, --erase           Erase before programming
  -f, --force           Force-erase before programming (implies -e)
  -d {ATF1502,ATF1504,ATF1508}, --device {ATF1502,ATF1504,ATF1508}
                        Device to program (default: ATF1502)
  -p PROGRAMMER, --programmer PROGRAMMER
                        Programmer device (default: /dev/cu.usbmodem14301)
```

#### Erase mode

This mode is used to erase an ATF150x device, and can also be used to 
force erase JTAG-locked or secured devices.

> **Note** that the force mode might be... _stressful_ for your device.

```
usage: atfu erase [-h] [-f] [-p PROGRAMMER] [-d {ATF1502,ATF1504,ATF1508}]

options:
  -h, --help            show this help message and exit
  -f, --force           Force erase
  -p PROGRAMMER, --programmer PROGRAMMER
                        Programmer device (default: /dev/cu.usbmodem14301)
  -d {ATF1502,ATF1504,ATF1508}, --device {ATF1502,ATF1504,ATF1508}
                        Device to erase (default: ATF1502)
```

#### Check mode

This mode is used to determine whether an ATF150x device is blank.

> **Note** Devices that cannot be communicated with will show up as `not blank`.
> In practice, this will always be either faulty, JTAG-locked or secured devices.
> For the former, it doesn't matter if they're blank or not, and for the latter,
> well, it's not possible for them to be blank anyhow...

```
atfu check [-h] [-p PROGRAMMER] [-d {ATF1502,ATF1504,ATF1508}]

options:
  -h, --help            show this help message and exit
  -p PROGRAMMER, --programmer PROGRAMMER
                        Programmer device (default: /dev/cu.usbmodem14301)
  -d {ATF1502,ATF1504,ATF1508}, --device {ATF1502,ATF1504,ATF1508}
                        Device to check (default: ATF1502)
```

#### Programmer mode

This mode can be used to list detected programmer boards, and query them.

```
atfu programmer [-h] {list,query} ...

positional arguments:
  {list,query}

options:
  -h, --help    show this help message and exit


atfu programmer list [-h] [--plain]

Functions for listing connected programmers

options:
  -h, --help  show this help message and exit
  --plain     Display a plain list of device paths
```

### Copyright

Copyright ©2024 [The Really Old-School Company Limited](https://rosco_m68k.com).

Portions Copyright (C) 2019-2020 whitequark@whitequark.org

Portions Copyright (c) 2015 Marcelo Roberto Jimenez <marcelo.jimenez (at) gmail (dot) com>

Portions Copyright 2008, SoftPLC Corporation  http://softplc.com [Dick Hollenbeck dick@softplc.com]

Mostly MIT License, portions under other licenses - see LICENSE.md & source code comments.


