Profile Editor

With the Profile Editor you create your own device profiles for add-ons or adapt existing ones. A profile defines how the nomos system Controller communicates with a device and what of it appears in the app, in automations and in Quick Config. Profile Format describes how a profile is built; the connection via TCP, UDP and HTTP is covered under CommandServer, ready-made examples under Example Profiles.

INFO

The Profile Editor is available if your licence unlocks it. Without it, the pencil icon and the New Profile button are missing from the profile list. On smartphones the editor is hidden.

Opening or creating a profile

All paths start under Skills → Add-ons in the Profiles tab:

• New Profile (plus icon, keyboard shortcut N): You enter a Name and select Protocol, Category and Type. The protocol (CommandServer, KNX, Modbus, MQTT, Z-Wave, ZigBee) determines the basic structure; the type provides a template with suitable actions, feedback values and templates, for example for a light, a dimmer or an inverter. Create opens the editor.
• Online Library: Loads a ready-made profile into the list. To edit it, then open it with the pencil icon.
• Manual Upload: Loads a profile file (.json, 1 MB at most) into the list. Older definition files in .csv format are converted into a JSON profile.
• Pencil icon in a row of the profile list: Opens the profile in the editor.

If a profile with the same name already exists, the import replaces it, and the devices that use it take over the new version (see Updates from the Online Library). A dot in the file name becomes _.

The quickest way is to start with a profile that is similar to your device, for example from the same manufacturer or with the same protocol, and to store it as a new profile with Save As.

Editor layout

At the top is the bar with the buttons Save As, Cancel and Save. On its left you choose which part of the profile you edit: the main profile or one of the sub profiles (see below). Below the bar, the editor shows the validation results, then the Info and Settings areas and below them the tabs.

Validation

The editor checks the profile with every change. The header counts errors (red), warnings (yellow) and notes (blue); if nothing is found, it shows No issues. Each row names the rule, the location in the profile and a message, for example consistency.polling at polling.Status.

The validation does not prevent saving. Still, fix errors before using the profile: they almost always point to a place where the device will later not respond or values will be missing.

Info

Field	Meaning
Description	Name of the profile in the profile list and suggestion for the device name
Manufacturer, Model	Details of the device
Platform	Origin of the device, e.g. the manufacturer name. Hidden and fixed for KNX and Z-Wave
Version	Increased automatically with every save (1.0 → 1.1) as long as you do not change it yourself. The version decides whether existing devices take over a change (see Changing a profile)
Author	Who created the profile
Support URL	Address of a help page for the device. It appears as an info button in the profile list and on the device page

Settings

Field	Meaning
Category, Type	Determine the icon and display in the app and whether the device appears via the Matter bridge. Choose the type that fits the most important value: a device that mainly reports motion is a motion sensor, even if it also delivers the temperature
Engine Type	How the controller addresses the device: CommandServer (own connection via TCP, UDP, HTTP or serial), MQTT, KNX, ZWAVE or BUS. The engine type determines which tabs are available
Class Name	CommandServer only: internal name of the connection, upper-case letters, digits, _ and - only. If the field stays empty, the editor builds it from manufacturer and model
Compatibility	How completely the profile covers the device, in percent
Certified by nomos system	Locked; only profiles checked by nomos system show Yes here
Tags	Additional tags, separated by comma or semicolon
Display Device in Apps	Without a tick, the device does not appear in the app
Use Device with Voice Assistants	Without a tick, the device is not passed on to voice assistants and the Matter bridge

The tabs

Tab	Content	Engine type
Communication	Connection settings: address, port, protocol, timeouts, reachability	CommandServer only
Actions	What can be sent to the device	all
Feedback	Which values the device reports	all
Pollings	Commands that are sent regularly to fetch values	CommandServer only
Cameras	Camera images the device provides	all
Webhooks	Values the device may send to the controller itself via HTTP	all

In every table, Add appends a row, the red ✕ deletes it, and dragging changes the order. Duplicate names are marked red.

Communication

The table has the columns Name, Value, Editable and Comment. You choose the name from the known settings or enter your own under User-defined.... What the settings do is described under CommandServer: Connection.

• Editable: The value is requested in Create device and pre-filled with the value entered here. Typical for the device's IP address, a port or credentials.
• Comment: The setting stays in the profile but has no effect. This is useful for keeping values that you only use as placeholders in commands (see Placeholders).

Actions and Feedback

Both tabs have the same layout. Use the bar with the jump links Communication, Definition and Templates to switch between the sections.

Communication (CommandServer only)

• Under Actions, this section lists the commands with Name, Sequence, Parameter, Timeout, Spacing and Tag; for HTTP additionally Method and, for POST, PUT, PATCH and DELETE, Content type and Body. \# in the sequence is the place for the value the action sends.
• Under Feedback, this section lists the patterns for the device's responses with Name, Match, Action, Condition, on Change and Tag.

CommandServer explains the meaning of each column.

Definition

Here you define what the app and automations see. Each row has Name, Command (for actions) or Feedback, Datatype and Unit.

• Name: Whenever possible, choose one of the suggested standard names such as state, level, position, setpoint or temperature. The app only knows these names for its controls; see Standard names.
• Command or Feedback: For CommandServer, select a command or a pattern from the Communication section. A command that starts with SET or GET is read as a property: SETCURR writes the property CURR. For KNX the field is fixed; you assign the group addresses only when you create the device.
• Datatype: null (button without a value), string, bool, trigger, int or float.
• Unit: For numbers. Categories lists units that the app converts for the user (e.g. temperature), Units lists fixed units such as W or kWh.

The pencil icon at the end of the row opens the Details dialog:

Field	Meaning
Description	Label in the app and in automations
Group	Section under which the app shows the value, e.g. “Charging” for a wallbox. Only useful for devices with many values
Hidden	The value does not appear as a separate row in the app but remains available for automations
Simulate Feedback	Actions only: the controller immediately reports the sent value as feedback, for devices without feedback of their own
Max. Length	Text only
Device min/max, Mapped min/max	Scaling between the device's value range and the one in nomos, see Scaling
Device unit, Kelvin warm/cold	Only for color-temperature: whether the device uses mired, kelvin or percent
Step Value	Step size of sliders
MQTT, MQTT Value, MQTT Unit, MQTT Payload	MQTT only, see MQTT
Size in Bit	For KNX, the size of the datapoint (1, 8, 16, 32 bit)
KNX DPT Filter	For KNX: which datapoint types are offered when assigning the group address
Value List	Selection values with text, e.g. 0 = Off, 1 = Level 1
Default Value	For actions, the value that is always sent (e.g. 1 for switchon); for feedback values, the initial value
Prefix, Suffix, Class Override	Actions only: text before or after the value; send the command to another connection
Process Function	Feedback values only: post-processing of the value, e.g. conversion into a price, see Processing
Matching Options, Volatile, mRemote Join	For special cases; leave empty in your own profiles

Templates

Templates are the entries that automations and Quick Config offer, e.g. “Turn On” or “Brightness”. Columns: ID, Name (the action or feedback value the template refers to), Icon, Description, Value and, for actions, Placeholder, plus Quick Config.

• Value: A fixed value. The automation then shows no input field, e.g. “Is Turned On” with the value 1.
• Placeholder: For actions with a text value, an example such as Welcome or http://…. It appears in grey in the action's still empty input field in automations. If the template has a fixed Value, the column is locked.
• Quick Config: A tick hides the template in the device's Quick Config; it remains available in automations.

WARNING

As soon as there is a single template, automations only offer the templates, no longer all actions or feedback values. Therefore, either create a template for every value that is needed in automations, or no templates at all.

Pollings

Each row has a Name, a Command and the Polling Interval (in Seconds). With Editable, the interval is requested when the device is created. An HTTP profile without a polling of its own receives the polling “Reachable Check” when saved, which fetches / every 30 seconds so that the reachability is correct.

Cameras

Each row has a URL and a URL Type: RTSP, Snapshot, MJPEG or Other HTTP. The URL may contain placeholders from the communication settings, e.g. http://%SERVERIP%/snapshot.jpg. When the device is created, one camera is created per row.

Webhooks

Here you select feedback values that the device may send to the controller itself, instead of the controller polling them. The address and how the device calls it are described under Webhooks.

Sub profiles

A device with several independent parts, e.g. an actuator with four channels, gets one sub profile per part. When the device is created, a separate device named “Device name Sub profile name” is created for each sub profile, all using the same connection.

• Create: In the selection on the left of the bar, choose Add..., enter an ID (lower-case letters, no dots or spaces) and optionally a Name.
• Delete: Delete Sub Profile in the Info of the sub profile. It is only deleted when you save.
• A sub profile only has the tabs Actions and Feedback. Connection, pollings and cameras belong to the main profile.

Saving

• Save writes the profile back under the same name. This also works when devices use the profile; they take over the change immediately (see Changing a profile). The profile then counts as changed in the Profile Editor.
• Save As creates a new profile; the previous one remains unchanged. If the name is already taken, _2, _3 etc. is appended.
• Cancel discards all changes without asking. The Esc key asks first. Ctrl+S or ⌘S saves.

When saving, the editor adds a few things itself:

• The Version increases by one if you have not changed it yourself.
• An empty Class Name is built from manufacturer and model.
• A feedback pattern that does not capture a value gets =1 appended to its name (see Name and value).
• For KNX and Z-Wave, platform and class name are set to fixed values and the feedback value reachable is removed.
• An HTTP profile without a polling receives the polling “Reachable Check”.
• If you change the engine type away from CommandServer, all settings, commands and patterns of the communication are dropped when saving.

Changing a profile

A changed profile takes effect immediately for new devices. For devices that already use the profile:

• The app and the configuration immediately show updated labels, groups, templates and value formatting.
• Existing devices take over commands, patterns, scaling, pollings and webhooks right after saving if the profile's Version is higher than the one the device was created with. The editor increases the version itself when saving; if you have set it manually, you must increase it yourself. For this, the controller rebuilds the devices: rooms, stored values, data recording and automations are kept; the devices cannot be operated for a moment.
• Existing devices do not take over cameras or newly added or removed sub profiles. Create the device again for this.

WARNING

Never rename the ID of a sub profile and never delete a sub profile that devices use: those devices will then show the values of the main profile.

Updates from the Online Library

If a profile you loaded from the Online Library appears there in a newer version, the profile list shows Update to … below the version and an Update to version … button in the row. A click replaces the profile with the new version; the devices that use it are updated right afterwards. In the Online Library itself, installed profiles are marked Installed or Update to …; importing again there also replaces the profile.

If you have changed the profile in the Profile Editor, the controller asks first, because the new version does not contain your changes:

• Replace applies the new version, also to the devices. Your changes are lost.
• As a copy leaves your profile and its devices unchanged and additionally stores the new version as a profile of its own.
• Cancel changes nothing.

Manual Upload asks the same question if it would replace a profile changed in the Profile Editor.

If the new version drops actions, feedback values or templates the profile had so far, the controller lists them first. Automations, scenes and tiles that use them stop working after the update. Update anyway replaces the profile, Cancel leaves everything as it is. Adjust the affected automations after the update.

For questions about profiles, contact support@nomos-system.com.