Creating Add-ons

What's in an Add-on?

An add-on is just a folder with your files and a description file that tells the system what to do with them:

my-addon/
├── manifest.json      # Describes your add-on (name, version, etc.)
├── files/             # The actual files to put on the Pi
│   ├── bin/           # Programs that can be run
│   ├── lib/           # Supporting files
│   └── etc/           # Settings files
├── install.sh         # What to do after installing (optional)
└── remove.sh          # What to do before removing (optional)

The Description File

The manifest.json file tells the system everything it needs to know about your add-on:

{
    "name": "my-addon",
    "version": "1.0.0",
    "description": "A short explanation of what this does",
    "author": "Your Name",
    "license": "MIT",
    "size_kb": 1500,
    "category": "utilities",
    "dependencies": ["python3"],
    "base_requirements": ["wifi"],
    "install_path": "/opt/modules/my-addon",
    "post_install": "install.sh",
    "pre_remove": "remove.sh",
    "provides": ["my-command"],
    "conflicts": []
}

What Each Field Means

Field	Required?	What It Does
name	Yes	A unique name for your add-on (lowercase, use dashes)
version	Yes	Version number (e.g., 1.0.0, 2.3.1)
description	Yes	A short sentence explaining what it does
dependencies	No	Other add-ons this one needs to work
base_requirements	No	Core features that must be turned on (e.g., "wifi")
size_kb	Yes	How much space it takes up (in kilobytes)
category	Yes	Which category it belongs to (gaming, utilities, etc.)
post_install	No	A script to run right after installing
pre_remove	No	A script to run before removing

Packaging Your Add-on

Bundle everything into a single downloadable file:

# From your add-on folder, create a package file
tar czf my-addon-1.0.0.tar.gz -C my-addon .

# You can host this file anywhere online
# or share it directly for local installation

What is tar.gz?

A .tar.gz file is like a ZIP file on Mac/Windows -- it bundles multiple files into one compressed download. The tar command creates them on Linux.

Installing from a File

You can install your add-on directly from a file on your Pi:

# Install from a file on your Pi
hamod install --local ./my-addon-1.0.0.tar.gz

# Or install from a web link
hamod install --url https://example.com/addons/my-addon-1.0.0.tar.gz

Tips for Good Add-ons