bin2woz

 _     _       ____                   
| |__ (_)_ __ |___ \__      _____ ____
| '_ \| | '_ \  __) \ \ /\ / / _ \_  /
| |_) | | | | |/ __/ \ V  V / (_) / / 
|_.__/|_|_| |_|_____| \_/\_/ \___/___|

A Node.js-based utility for converting binary files to Wozmon formatted text.

Wozmon — Steve Wozniak's 256-byte Apple 1 monitor — takes memory deposits in the form ADDR: XX XX XX. That is all this tool emits, so its output can be pasted over a serial terminal into any machine running Wozmon or a compatible monitor, on the Apple 1 or otherwise.

Installation

From NPM

npm install -g bin2woz

From Source

1. Clone the repository:

git clone https://github.com/acwright/bin2woz.git
cd bin2woz

2. Install dependencies:

npm install

3. Build the project:

npm run build

4. (Optional) Link globally:

npm link

Usage

Basic Usage

Convert a binary file to Wozmon format starting at address 0x0000:

bin2woz <path-to-binary-file>

With Custom Starting Address

Specify a custom starting address in hexadecimal:

bin2woz -a 0x800 <path-to-binary-file>

or

bin2woz --address 0x800 <path-to-binary-file>

Redirect Output to File

bin2woz -a 0x800 program.prg > output.txt

Command Line Options

• -v, --version - Output the current version
• -h, --help - Display help information
• -a, --address <address> - Starting address in hexadecimal (default: 0x0000)

Output Format

The tool outputs binary data in hexadecimal format with 16 bytes per line:

0800: AA BB CC DD EE 00 11 22 33 44 55 66 77 88 99 FF
0810: 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 10

Each line contains:

• 4-digit hexadecimal address
• Colon separator
• Up to 16 bytes in hexadecimal format, space-separated

Example

# Convert a 6502 program binary starting at address 0x800
bin2woz -a 0x800 /path/to/binary/file.bin > output.txt

Development

Run in Development Mode

npm run build
node ./dist/index.js -a 0x800 <path-to-binary-file>

Release Build

git tag vX.Y.Z
git push origin main --tags
npm publish

Project Structure

bin2woz/
├── src/
│   ├── index.ts              # CLI entry point
│   └── Bin2Woz/
│       └── Bin2Woz.ts        # Core conversion logic
├── dist/                     # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

License

MIT: https://github.com/acwright/bin2woz/blob/main/LICENSE

Credits

Inspired by: https://github.com/simonsunnyboy/bin2woz