Catalog

The HSYCO device catalog is stored in catalog.json, located in the config directory of the HSYCO root directory. It defines all devices available in the system, organized into groups, and is managed through the HSYCO Web interface.

Automatic Migration from systemtopo.txt

Older HSYCO installations used a plain-text file called systemtopo.txt to define devices and Wi-Fi location zones. This format is no longer used. On first startup, HSYCO automatically converts the file to the new catalog format:

• If systemtopo.txt exists and catalog.json does not exist, HSYCO performs a one-time conversion automatically.
• After the conversion, catalog.json is created and used from that point on. The original systemtopo.txt is left in place but is no longer read.
• A confirmation message is written to the log: systemtopo.txt converted successfully.

Device Conversion

Each device entry in systemtopo.txt is converted to a JSON object in the devices array of catalog.json. The fields map as follows:

systemtopo.txt field	catalog.json field	Notes
id prefix (before first .)	ioServer	The I/O Server name
id remainder (after first .)	id	The device data point ID
function (first ; field)	function	LIGHT, AUTOM, etc.
type (second ; field)	type	STD, LIGHT, DIMMER, VSHUT, HSHUT, LOCK, ONOFF, SCENE
image filename or cam:N	image	Optional
description text	description	Stored as {"en": "..."}

Example conversion:

# systemtopo.txt
(devices)
k.light.14 : LIGHT ; LIGHT ; entrance.jpg ; Entrance
k.autom.14 : AUTOM ; VSHUT ;

Becomes in catalog.json:

{
  "devices": [
    {
      "id": "light.14",
      "ioServer": "k",
      "function": "LIGHT",
      "type": "LIGHT",
      "image": "entrance.jpg",
      "description": { "en": "Entrance" }
    },
    {
      "id": "autom.14",
      "ioServer": "k",
      "function": "AUTOM",
      "type": "VSHUT",
      "image": null,
      "description": {}
    }
  ],
  "groups": []
}

Location Conversion

The (location) section of systemtopo.txt associates Wi-Fi access point IDs with human-readable zone names. During conversion these labels are not written to catalog.json; instead they are appended as DefaultLabel parameters in hsyco.ini, directly after their corresponding LocationBaseIP or LocationBaseBeacon entry.

For each location line in systemtopo.txt:

<id> : <zone name>

HSYCO adds to hsyco.ini:

LocationBaseIP.<id>.DefaultLabel = <zone name>

or

LocationBaseBeacon.<id>.DefaultLabel = <zone name>

For example:

# systemtopo.txt (location section)
1p : FIRST FLOOR
open : OPEN SPACE

Results in hsyco.ini additions:

LocationBaseIP.1p = ...
LocationBaseIP.1p.DefaultLabel = FIRST FLOOR
LocationBaseBeacon.open = ...
LocationBaseBeacon.open.DefaultLabel = OPEN SPACE

The label is only added if a matching LocationBaseIP or LocationBaseBeacon entry already exists in hsyco.ini and a DefaultLabel line is not already present.

catalog.json Structure

The file contains two top-level arrays:

{
  "devices": [ ... ],
  "groups": [ ... ]
}

Device Object

Field	Type	Required	Description
ioServer	string	yes	The I/O Server name
id	string	yes	The data point ID within the I/O Server
function	string	no	LIGHT, AUTOM, DIMMER, or BINARY
type	string	no	STD, LIGHT, DIMMER, VSHUT, HSHUT, LOCK, ONOFF, SCENE
image	string	no	Image filename (from www/img) or cam:N for a camera
description	object	no	Localized name, e.g. {"en": "Entrance", "it": "Ingresso"}
groups	array	no	List of group IDs this device belongs to

Group Object

Field	Type	Required	Description
id	string	yes	Unique group identifier
name	object	yes	Localized group name, e.g. {"en": "Ground Floor"}
description	object	no	Localized group description
parentId	string	no	ID of the parent group, for nested hierarchies

File Changes and Error Handling

HSYCO monitors catalog.json for changes and automatically reloads it within a few seconds of any modification. There is no need to restart HSYCO or reload the Web Interface.

After each reload attempt, the result is reported in the log with one of the following messages:

• config/catalog.json loaded successfully. — the file was parsed and all entries loaded without errors
• config/catalog.json loaded partially. — the JSON structure is valid but one or more entries contain errors; valid entries are loaded and active, invalid ones are skipped
• Failed to load config/catalog.json: <error details> — a JSON syntax error prevented the file from being parsed at all; the previously loaded catalog remains active unchanged

Individual entry errors are logged before the summary line and always include the file line number of the affected entry:

Invalid Device declaration at line 42, missing 'ioServer'
Invalid Group declaration at line 17, duplicate 'id'
Parent group 'floor2' not found for group 'room3' at line 55
Device 'knx.1/1/1' at line 68 references missing group 'floor2'

On a JSON syntax error the file is retried on the next poll cycle, so the error will be logged repeatedly until the file is corrected.