RoboHub

This page was generated from the source of RoboHub. Edit the source, not this page.

Inventory & expenses

What is on the shelf, what is installed, and what it cost — and, when the
application binds a gateway, which device each piece of equipment is. The module
has pages, a backend and SQL tables; it has no port of its own. A host
application includes it and the module registers its pages on the host's router
(/expenses, /devices). Aquarium and energy include it.

How an application uses it

Include the module and add it to deps. It brings i18n, settings,
notifications, forms and the robohub.gateway interface — the interface
only, never a provider. An application that binds a gateway (see
robohub-gateway-contract/index) can connect equipment to devices; one that
binds none still has an inventory.

The application:

  • defines host_shell(req, title, body, scripts): the module's pages render
    content only, so the header, footer and menu are always the application's. The
    inventory's CSS travels with the content;
  • seeds its categories at startup with inventory_presets(text) (below);
  • calls inventory_runtime_tick() from its background work, if it wants switch
    runtime counted;
  • defines the host_devices_* hooks for the Devices page (below);
  • adds the module's settings tab: inventory_settings_form and
    inventory_settings_save, combined through host_settings_tabs/form/save (see
    appshell/index).

What it records

An item has a name, a category, a unit, a quantity on hand, a reorder level,
a location and notes. The inventory page shows what is on hand and marks an item
that has reached its reorder level.

A purchase has an item, a category, a quantity, a unit price, a store, a
date and a comment. Recording one adds the spending and increases the item's
stock. Money is integer cents and quantity is thousandths, so a total does not
depend on floating-point spelling.

Stock also leaves the shelf through Remove from stock, which records a
negative movement. An item can be edited without losing its quantity or its
purchase history.

Kinds, handles and categories

Everything an installation has is an item, of one of three kinds:
consumable (used up: food, fertiliser, test reagents), part (fitted and
replaced: filter media, fuses) and equipment (installed: the filter, the
heater, the light). An item's handle — filter-main — is the name every
other part of the application uses for it.

The categories are the application's. It seeds them from the text of its
presets/inventory.yml by calling inventory_presets(text):

categories:
  food:
    name: Food
    kind: consumable
  filters:
    name: Filters
    kind: equipment
    capabilities: switch, power?
  feeders:
    name: Feeders
    kind: equipment
    capabilities: press
    uses: Food

A category's capabilities are what an equipment item in it can be bound to; a
trailing ? marks one that may stay unbound. uses names the category one use
of the item consumes from. A preset category keeps its name; a category a person
adds may be renamed or deleted.

Automation

When the application binds a gateway, an equipment item has an Automation
tab: one row per capability of its category, each bound to a gateway source
chosen from the sources reporting that signal. A capability the item drives (a
switch) is bound for control, one it only reports (power, temperature) for
reading; a source is controlled by one item at most, so two items cannot fight
over one relay.

Rules, dashboard cards and chores name handle.capability, never a device.
Replacing a plug is one binding changed; nothing that names the item changes.
What the application and other modules call:

FunctionWhat it does
inventory_resolve(handle, capability)The gateway source bound to it, or ""
inventory_read(handle, capability)Its newest reading
inventory_switch(handle, on, actor)Switches it through the gateway, and logs who asked
inventory_consume(handle, quantity_milli, reason, for_ref), inventory_return(...)Takes stock off, or puts it back, with a movement saying why
inventory_use(handle, actor)One use of an item that uses a category (a feeder's portion)
inventory_runtime_tick(), inventory_runtime_seconds(handle)Counts switch runtime from the gateway's history; the runtime counted so far
inventory_choices(category, kind), inventory_item_name(handle), inventory_item_id(handle)Items as choices for a form; one item's name; its id
inventory_automated()Whether a gateway is bound

The Devices page

/devices is where an application says what is behind each piece of equipment
its rules name: which item, and which gateway source each of its capabilities
reads. It is one page for every application, in sections the application names,
and a section shows either or both of:

  • roles — a handle the rules use (heater), filled by one item at a time:
    any equipment, or a new item made for it. Choosing another item moves the
    handle to it;
  • items — every equipment item of the section's categories, with a form to
    add another to one of them.

What differs between applications is asked of the application:

HookAnswers
host_devices_sections(req)One section per line, `keylabel`; an empty label shows no heading
host_devices_roles(req, key)The section's roles, one per line: `handlelabelcategorycapabilitieshint`
host_devices_categories(req, key)The categories the section lists and adds to, comma-separated, or ""
host_devices_query(req)What the page keeps in its address across a save (tank=2), or ""
host_devices_intro(req)What is shown above the sections (a tank chooser), or ""
host_devices_value(capability, text)A reading as the page shows it (1.2 kW)
host_devices_added(id, category)What follows an item added on the page
host_devices_changed(handle, what)A mapping changed; the application's journal is the usual place

The aquarium has one unnamed section of roles, one tank at a time; energy has a
section per group (generation, storage, grid, loads) listing its equipment. An
item is only ever added to a category its section offers.

Settings

Kept in the application's settings store (see settings/index) and shown
on the module's settings tab:

KeyDefaultWhat it is
inventory.currencyRONThe currency prices are shown in (RON, EUR, USD)
inventory.default_unit—The unit a new item starts with
inventory.reorder0The reorder level a new item starts with

An application from before the settings store kept these as a config: map on
the module's entry under app_modules: in its manifest (ROBOHUB_APP_MANIFEST);
that map is still read when the store has no value.

Data it keeps

The records belong to the application that includes the module, not to the
module: they are in the application's database, <workspace>/data/app.db (or
RHO_INVENTORY_DB), so two applications using the module never share data.

TableWhat it holds
categoriesThe categories, their kind, capabilities and what they use; whether a preset or a person made each
itemsWhat is on hand: kind, handle, quantity, reorder level, location, switch runtime, a use's portion
item_bindingsWhich gateway source each equipment capability is bound to, and whether for control or reading
expensesOne purchase line each, in cents and thousandths
stock_movementsEvery change to the stock, signed, with why

db/schema.sql and db/queries.sql are the module's own, declared in its
sql: block. rho-sql generates them into every application that depends on the
module, before the application's own statements, so an application does not
repeat them. A column added in a later version is both in its table's CREATE
and in an ALTER TABLE ... ADD COLUMN after it, so a new database and an older
one end with the same table.

Item saves, deletions, bindings and switches are written to the application log
under the inventory subject.

Reference

Generated from the module's manifest and sources when this site was built.

Exports — what an application may call (provides.exports, imported as robohub.inventory):

  • inventory_binding_source
  • inventory_automated
  • inventory_resolve
  • inventory_read
  • inventory_switch
  • inventory_consume
  • inventory_return
  • inventory_use
  • inventory_choices
  • inventory_item_name
  • inventory_item_id
  • inventory_presets
  • inventory_runtime_tick
  • inventory_runtime_seconds
  • inventory_add_named
  • inventory_quantity
  • inventory_handle
  • inventory_settings_form
  • inventory_settings_save

Routes — registered on the host application's router:

MethodPathHandler
GET/expensesinventory_page
GET/api/expenses/countinventory_count
GET/expenses/items/editinventory_edit_page
POST/expenses/items/addinventory_items_add
POST/expenses/items/editinventory_items_edit_save
POST/expenses/items/consumeinventory_items_consume
POST/expenses/purchases/addinventory_expenses_add
POST/expenses/purchases/deleteinventory_expenses_delete
POST/expenses/categories/addinventory_categories_add
POST/expenses/categories/renameinventory_categories_rename
POST/expenses/categories/deleteinventory_categories_delete
POST/expenses/items/deleteinventory_items_delete
GET/expenses/items/automationinventory_automation_page
POST/expenses/items/bindinventory_items_bind
POST/expenses/items/switchinventory_items_switch
GET/devicesinventory_devices_page
POST/devicesinventory_devices_save
POST/devices/addinventory_devices_add

Host hooks — functions the application must define, because this module calls them:

  • host_devices_added
  • host_devices_categories
  • host_devices_changed
  • host_devices_intro
  • host_devices_query
  • host_devices_roles
  • host_devices_sections
  • host_devices_value
  • host_shell

Release history

[0.1.0] - 2026-11-02

The inventory and expense module. Stock on hand, reorder levels, categories, locations and notes; purchases that add stock and spending together; stock removal; a low-stock list; item editing; and purchase history and totals, stored in the host application's main SQLite database.

[0.1.1] - 2026-11-03

The inventory page carries the same full application menu as the dashboard.

[0.1.2] - 2026-11-08

English/Romanian navigation and page copy, forms-engine add flows with CSRF and input-mode support, and settings moved to the parent application.

[0.1.3] - 2026-11-09

Pages render content through the host shell, so the host application owns the header, footer and menu. The inventory CSS moved into templates/parts/style.html with the content. Item saves are written to the host application log.

[0.1.4] - 2026-11-12

The module declares the runtime functions it calls and discards results by calling directly, rather than relying on helpers the including application defines. Its smoke test signs in with a keeper ticket and sends the form token the module checks.

[0.2.0] - 2026-11-13

Inventory is where every item of an installation lives, equipment included. An item has a kind (consumable, part, equipment) and a handle that the rest of an application names it by. Categories carry a kind, the capabilities an equipment item in them can be bound to (switch, power?) and the category they use, and an application seeds them from its presets (inventory_presets). An equipment item's Automation tab binds each capability to a gateway source; a source is controlled by one item at most. inventory_resolve, inventory_read, inventory_switch, inventory_consume, inventory_use and inventory_runtime_tick are what applications and other modules call. The gateway is the interface only: an application that binds none has the inventory it had.

The module's tables and statements are its own, declared in its sql: block and generated into each application by rho-sql 0.2; older databases get the new columns from ALTER TABLE statements. The smoke test runs in the aquarium's own repository and covers the migration, handles and bindings. inventory_assign_handle, inventory_add_equipment and inventory_bind let an application fill the roles its rules name (heater, light) from a page of its own. An item that is not bound is no longer warned about on every switch attempt; the rule that asked says so.

[0.2.1] - 2026-11-13

The page's message (?msg=) is written into its toast as a JavaScript string, so a crafted link can no longer run script on the inventory page.

[0.2.2] - 2026-11-13

The clock is read from the process (rho_now_s, rho 0.6.0) instead of from date written to a file and read back, which a request and the background loop could truncate under each other: entries dated 1970 and modes that expired at once. Today's date likewise (rho_local_date).

[0.2.3] - 2026-11-13

A purchase's total is reckoned in 64 bits (100 units at 500.00 overflowed); a stock taken below zero is shown negative instead of as four billion; a decimal comma (2,50) is a decimal point; a capability bound from the Automation tab is kept under its name (power, not power?), so it is found again.

[0.2.4] - 2026-11-14

Trimming, URL escapes, form fields and decimals come from the toolchain (rho 0.7.0: str_trim, str_url_encode/str_url_decode, form_field, milli_*) rather than this module's own copy, the same on both backends. Needs rho 0.7.0. The unprefixed trim, url_decode and form_value this module leaked into every application are gone; a % not followed by two hex digits is kept as written instead of becoming a zero byte.

[0.3.0] - 2026-11-14

The Devices page is the inventory's: /devices, one page for every application, where what is behind each piece of equipment is chosen — which item fills a role the rules name, and which gateway source each capability reads — and equipment is added to a section's categories. The aquarium and energy each had their own; what differs between them is asked of the application through host_devices_* functions, which an application that includes the inventory now defines (see Devices in the docs). An item is only added to a category its section offers.

[0.3.1] - 2026-11-14

One item is looked up, not found in a list of every item: inventory_resolve — what every reading and switch of a rule goes through — reads the item by handle or id and its one binding, where it read up to 512 items and 512 bindings each time; inventory_item_id, inventory_item_name, inventory_consume and inventory_runtime_seconds likewise. Its route handlers, helpers and constants carry the module's prefix; unprefixed, they were in the namespace of every application that includes the module. (items_add is inventory_items_add, unquote is inventory_unquote, ITEM_CAPACITY is INVENTORY_ITEM_CAPACITY, and so on.)

[0.3.2] - 2026-11-14

Its data is kept where app_workspace() says (rho 0.8.0) — the application's workspace, else ~/.rho/apps/<app> — so two applications started by hand no longer share this module's records. Copies of helpers the toolchain now provides (i64_to_str, str_lower, str_field, json_str_field, escape_html) are gone. It declares the i18n module it uses. Needs rho 0.8.0.

[0.3.3] - 2026-11-14

An item can be deleted from its edit page (its bindings and stock history go with it; its purchases stay in the expenses), and a category a person added can be renamed, or deleted while empty — a category the application's presets keep (origin = 'preset') cannot, since the application reads it by name. The item edit form carries the form token. inventory_return puts stock back, the opposite of inventory_consume.

[0.3.4] - 2026-11-14

Its settings form is its own (inventory_settings_form, inventory_settings_save), shown by an application as one of its settings tabs.

[0.4.0] - 2026-11-14

It lists what other code may use (provides.exports, imported as robohub.inventory). An application that includes it still reaches everything, and a build (rho 0.8.3) names each call to a function outside the list. The list is what the applications and modules of the ecosystem call; anything else is the module's own and may change without notice.