ProtoShelf Documentation

ProtoShelf is a comprehensive inventory management system designed for electronics enthusiasts, makers, and professionals to organize and track their electronic components efficiently.

๐Ÿ“‹

Component Tracking

Track quantities, costs, and specifications of electronic components with detailed information and custom categories.

๐Ÿ“ฆ

Smart Organization

Organize components in bins and units with visual layouts that match your physical storage system.

๐Ÿ’ก

WLED Integration

Visual component location with LED strip integration for easy finding in large storage systems.

Getting Started

Quick Start - For Users: ProtoShelf comes as a single executable file - no complex installation required!
1
Download

Download the ProtoShelf zip file from releases

2
Extract

Extract the zip file to your desired folder

3
Run

Double-click protoshelf.exe to start

That's it! ProtoShelf will start automatically and appear in your system tray. Click the tray icon to open the web interface at http://localhost:3001

For Developers

If you want to modify or contribute to ProtoShelf, you'll need the development environment:

Prerequisites
  • Go 1.23.4+
  • Node.js 16+ and npm
  • Git
Build Commands
git clone oiLAINio/protoshelf cd protoshelf ./build.ps1 # Windows # or ./build.bat

Key Features

Component Management

Track Components
  • Component name and description
  • Quantity tracking
  • Cost and purchase information
  • Datasheet and order links
  • Custom category assignments
Organization
  • Bin-based storage system
  • Unit layouts with visual positioning
  • Custom categories with inputs
  • Search and filter capabilities

Storage Units & Bins

Organize your components using a hierarchical system of units and bins:

Units

Physical storage containers (drawers, boxes) with configurable layouts and optional WLED integration for visual location assistance.

Bins

Individual compartments within units that can hold multiple components with precise positioning and sizing.

WLED Integration

Connect LED strips to your storage units for visual component location:

  • Configure WLED IP addresses for each unit
  • Visual highlighting of component locations
  • Matrix-based LED positioning
  • Remote LED control via network

First Time Setup

๐Ÿ“‹ Configuration File

ProtoShelf uses a configuration file to manage settings. The default configuration file is located in the root of the ProtoShelf directory and is named server.yaml. You can edit this file to customize your ProtoShelf server settings.

Default Configuration (server.yaml):

database:
    autobackup: true        # Enable automatic backups of the database
    backupinterval: 24      # Backup interval in hours
    maxbackups: 7           # Maximum number of backups to keep
    sqlite:
        path: data/sqlite/protoshelf.db  # Path to the SQLite database file

logging:
    format: text           # Log format (text or json)
    level: debug          # Log level (debug, info, warn, error)
    file: true            # Enable logging to file other than console

server:
    port: 80              # Port on which the server will run

๐Ÿ” Setting the JWT Secret Environment Variable

โš ๏ธ Important: To keep your ProtoShelf server secure, you must set a JWT_SECRET environment variable before running the application. This secret is used to sign and verify authentication tokens.

Windows Setup

Step 1: Generate JWT Secret

In your ProtoShelf directory, run the batch file:

generate_jwt_secret.bat
Step 2: Set Environment Variable (Temporary)

You will see an output with a key. Copy the command and run it in your terminal:

set JWT_SECRET=your-generated-secret
Step 3: Set Environment Variable (Permanent - Optional)

To set the JWT_SECRET variable permanently:

  1. 1. Open Start Menu and search for "Environment Variables"
  2. 2. Click Edit the system environment variables
  3. 3. In the System Properties window, click Environment Variables...
  4. 4. Under User variables, click New...
  5. 5. Enter JWT_SECRET as the variable name
  6. 6. Paste your generated secret as the value
  7. 7. Click OK to save

Linux Setup

Step 1: Generate JWT Secret

In your ProtoShelf directory, run the shell script:

./generate_jwt_secret.sh
Step 2: Set Environment Variable (Temporary)

Copy the command from the output and run it:

export JWT_SECRET="your-generated-secret"
Step 3: Set Environment Variable (Permanent)

Add the export line to your shell profile:

# For bash users:
echo 'export JWT_SECRET="your-generated-secret"' >> ~/.bashrc
# For zsh users:
echo 'export JWT_SECRET="your-generated-secret"' >> ~/.zshrc

๐Ÿš€ Opening ProtoShelf for the First Time

Once you have set up the configuration file and the JWT secret, you can start your ProtoShelf server and access it in your web browser.

๐ŸŽ‰ Admin Account Setup: When you run the ProtoShelf server for the first time, you will be taken to a setup page where you can create an admin account. This account will have full access to manage your ProtoShelf server.

Step 1: Launch ProtoShelf

Double-click protoshelf.exe (Windows) or run the executable (Linux). The app will start and appear in your system tray.

Step 2: Open the Interface

Right-click the ProtoShelf icon in your system tray and select "Open ProtoShelf" or visit http://localhost (or the port you configured)

Step 3: Complete Initial Setup

Follow the setup wizard to create your admin account and configure initial settings

Step 4: Set Up Your Storage

Navigate to the "Units" tab to create your first storage unit (drawer, box, cabinet, etc.)

How to Use ProtoShelf

Managing Storage Units & Bins

Creating Units
  1. Go to the "Units" page
  2. Click "Add Unit"
  3. Enter a name (e.g., "Resistor Drawer", "IC Cabinet")
  4. Set the number of columns for your layout
  5. Optionally add WLED IP for LED integration
  6. Click "Save"
Adding Bins to Units
  1. Click on a unit to view its layout
  2. Click "Add Bin"
  3. Enter a label (e.g., "1kฮฉ Resistors", "ATmega328")
  4. Position and size the bin in the grid
  5. Save your changes
Pro Tips for Organization:
  • Use descriptive names for units (e.g., "Passive Components Drawer 1")
  • Keep bin labels specific (value, part number, or description)
  • Group similar components in the same unit
  • Use the visual layout to match your physical storage

Managing Components

Adding Components
  1. Go to the "Inventory" page
  2. Click "Add Component"
  3. Fill in component details:
    • Name: Component identifier
    • Quantity: How many you have
    • Category: Type of component
    • Cost: Price per unit
    • Description: Additional details
    • Datasheet Link: Link to specs
    • Order Link: Where to buy more
  4. Assign to bins for physical location
  5. Save the component
Managing Inventory
  • Update Quantities: Click on a component and modify the quantity as you use parts
  • Search & Filter: Use the search bar to quickly find components
  • Edit Details: Click the edit icon to update information
  • Find Location: Use the locate feature to highlight where a component is stored
  • Reorder Tracking: Use the order link when quantities get low
Component Entry Best Practices:
  • Include part numbers in component names for easy identification
  • Use consistent naming conventions (e.g., "Resistor 1kฮฉ 1/4W")
  • Add datasheet links for quick reference during projects
  • Keep order links updated for easy reordering
  • Update quantities immediately after using components

Categories & Custom Fields

Using Categories

Categories help organize components by type and can include custom input fields specific to that category.

  • Resistors: Value, tolerance, wattage
  • Capacitors: Value, voltage rating, type
  • ICs: Part number, package, function
  • Connectors: Pin count, type, pitch
Custom Input Fields

Each category can have custom fields that appear when adding components of that type.

Example: A "Resistor" category might have custom fields for "Resistance Value", "Tolerance", and "Power Rating" that automatically appear in the component form.

WLED Integration (Optional)

Connect LED strips to your storage units for visual component location. Perfect for quickly finding components in large storage systems.

Setup Process
  1. Install WLED on ESP32/ESP8266 controllers
  2. Mount LED strips around your storage units
  3. Configure WLED with your network settings
  4. In ProtoShelf, edit your unit and add the WLED IP address
  5. Test the connection using the locate feature
Using the Locate Feature
  • Click "Locate" next to any component
  • The corresponding bin area will light up
  • Great for finding components in dim lighting
  • Especially useful in large storage systems

Backup & Data Management

Manual Backup & Restore

Creating Backups
  1. Go to the "Settings" page
  2. Click "Create Backup"
  3. A JSON file will be downloaded automatically
  4. Store this file safely (cloud storage, external drive)
Backup files contain your complete inventory data
Restoring from Backup
  1. Go to the "Settings" page
  2. Click "Import Data"
  3. Select your backup JSON file
  4. Confirm the import process
This will overwrite existing data with matching IDs

Setting Up Automatic Backups

ProtoShelf can automatically create backups of your database at regular intervals.

Configuration

Edit the server.yaml file in your ProtoShelf directory:

backup: enabled: true interval: "24h" # Daily backups retention: 7 # Keep 7 backups
Backup Schedule Options
  • "1h" - Every hour
  • "6h" - Every 6 hours
  • "24h" - Daily (recommended)
  • "168h" - Weekly
Restart ProtoShelf after changing backup settings

Managing Automatic Backups

Viewing Available Backups

Use the Settings page to:

  • View all automatic backups with timestamps
  • Restore from any backup point
  • See backup file sizes and creation dates
Backup Storage Location

Automatic backups are stored in: data/sqlite/backups/

Backup Best Practices:
  • Always test restore procedures with backup files
  • Store manual backups in multiple locations (cloud, external drive)
  • Export data before major changes or updates
  • Check backup logs periodically to ensure automation is working

Workflow Tips & Best Practices

Recommended Workflow

1. Plan Your Layout
  • Sketch your physical storage
  • Group similar components
  • Consider frequency of use
  • Plan for growth
2. Set Up Digital Structure
  • Create units first
  • Add bins to match physical layout
  • Test the visual arrangement
  • Configure WLED if using
3. Populate Inventory
  • Start with most-used components
  • Use consistent naming
  • Add detailed specifications
  • Include purchase information

Pro Tips for Efficient Management

Organization Strategies
  • By Type: All resistors in one unit, capacitors in another
  • By Project: Group components for specific projects together
  • By Value: Organize components by value ranges within types
  • By Frequency: Keep commonly used parts easily accessible
Maintenance Habits
  • Update Immediately: Change quantities as soon as you use components
  • Regular Audits: Periodically verify digital vs. physical inventory
  • Reorder Alerts: Set mental triggers for low-quantity components
  • Document Projects: Note which components were used for what
Power User Features
Keyboard Shortcuts & Speed
  • Use the search bar for quick component lookup
  • Bookmark frequently accessed component pages
  • Use browser tabs for multiple views
  • Set up quick access toolbar bookmarks
Advanced Organization
  • Use component descriptions for search keywords
  • Include alternative part numbers in names
  • Use consistent abbreviations (e.g., "uF" vs "ยตF")
  • Tag seasonal or project-specific components

API Reference

For Developers: This section is primarily for developers who want to integrate with ProtoShelf or build custom tools. Regular users can safely skip this section.

Components API

GET /api/components
Retrieve all components
POST /api/components
Create a new component
PATCH /api/components/{id}
Update an existing component
DELETE /api/components/{id}
Delete a component

Locations API

GET /api/locations
Retrieve all storage units
POST /api/locations/unit
Create a new storage unit
POST /api/locations/{unitId}/bins
Add bin to a specific unit
PATCH /api/locations/{unitId}/bins/{binId}
Update a bin

Backup API

GET /api/backups/export
Download complete backup as JSON
POST /api/backups/import
Import data from backup JSON
POST /api/backups/create
Create a manual backup
GET /api/backups/list
List all available backups

Other APIs

GET /api/categories
Retrieve all component categories
POST /api/locate
Trigger WLED location highlighting
GET /api/settings/system
Get system information

Configuration

Server Configuration

ProtoShelf uses a YAML configuration file located at server.yaml in your installation directory. 

database:
    autobackup: true        # Enable automatic backups of the database
    backupinterval: 24      # Backup interval in hours
    maxbackups: 7           # Maximum number of backups to keep
    sqlite:
        path: data/sqlite/protoshelf.db  # Path to the SQLite database file

logging:
    format: text           # Log format (text or json)
    level: debug          # Log level (debug, info, warn, error)
    file: true            # Enable logging to file other than console

server:
    port: 80              # Port on which the server will run

Database Settings

  • autobackup: Enable automatic database backups
  • backupinterval: Hours between automatic backups
  • maxbackups: Maximum number of backup files to retain
  • sqlite.path: Path to the SQLite database file

Server & Logging

  • server.port: Web interface port (default: 80)
  • logging.level: debug, info, warn, error
  • logging.format: text or json
  • logging.file: Enable file logging

Backup & Restore

Export Data

Export your entire inventory as a JSON file for backup or migration purposes.

GET /export

Downloads a complete backup as protoshelf_backup.json

Import Data

Import data from a previously exported JSON file. This will upsert (insert or update) all data.

POST /import

Accepts JSON data to restore inventory

Automated Backups

POST /backup/create

Create a manual backup

GET /backup/list

List all available backups

POST /backup/restore

Restore from a specific backup file

Important Note

Always create a backup before performing major operations. The import function will overwrite existing data with matching IDs.