Assistant aliases and scripts can be imported from a YAML file (.yaml). This page describes every field of the file, version 1. For how to import a file and manage what it contains, see Aliases and Scripts.
The quickest start is the template in the app: Assistant → ☰ → Help → Aliases & scripts → Download template. It contains one example of everything, ready to import.
Structure
version: 1
prompt: # aliases - tied to the ETS project loaded when you import
entities: []
groups: []
rooms: []
phrases: []
cli:
scripts: [] # scripts - available in every project
| Field | Required | Description |
|---|---|---|
version |
Yes | Must be 1 |
defaults.locale |
No | Accepted for portability; not used yet |
prompt |
No | Aliases - entities, groups, rooms, and phrases |
cli |
No | scripts |
A file needs at least one alias or one script. Lists you don't use can be left out. Unknown fields are errors.
A file with aliases can only be imported while an ETS project is loaded, and the aliases belong to that project - importing them replaces the project's alias set. Scripts don't belong to a project; each is added to your scripts, and one with the same name as an existing script replaces it.
Fields of every entry
| Field | Required | Default | Description |
|---|---|---|---|
name |
Yes | - | The words that trigger it |
aka |
No | [] |
Other words that trigger it, e.g. [my lamp, sofa light] |
enabled |
No | true |
false keeps the entry but turns it off |
note |
No | - | Your own note; the assistant ignores it |
override |
No | false |
Aliases only: true makes the alias win over a same-named item in the ETS project |
Names are compared ignoring case and surrounding spaces. Every name and aka must be unique among all aliases, and separately among all scripts - an alias and a script may share a name.
Entities
One friendly name for one group address.
prompt:
entities:
- name: reading lamp
aka: [my lamp]
address: 1/2/3
dpt: "1.001"
note: beside the sofa
| Field | Required | Description |
|---|---|---|
address |
Yes | The group address, main/middle/sub |
dpt |
No | A datapoint type hint, in quotes. The loaded project's type wins. |
An address that is not in the loaded project is a warning, not an error - the alias still writes to that address, which is useful for commissioning and testing.
Groups
One name for several group addresses. Writing to a group always needs strong confirmation.
prompt:
groups:
- name: downstairs lights
aka: [lower floor lights]
members:
- 1/1/1
- 1/1/2
- ref: reading lamp
| Field | Required | Description |
|---|---|---|
members |
Yes | Group addresses, or ref: followed by the name of an entity in the same file |
Rooms
A room of your own, for when the ETS project has no useful room grouping. Each member has a type, so set home office temperature to 21 changes only the room's temperature addresses.
prompt:
rooms:
- name: home office
aka: [office, study]
members:
- { address: 4/1/1, type: light }
- { address: 4/1/2, type: blind }
- { address: 4/1/3, type: temperature }
| Field | Required | Description |
|---|---|---|
members[].address |
Yes | The group address |
members[].type |
Yes | What it is, for example light, blind, or temperature - use the word you will use in requests |
Rooms can only be created in a file; in the app they can be turned on or off and deleted.
Phrases
A shortcut for a complete request. The assistant reads the phrase as that request, with the usual clarification and confirmation.
prompt:
phrases:
- name: good night
aka: [bedtime]
expands_to: "turn all kitchen lights off"
| Field | Required | Description |
|---|---|---|
expands_to |
Yes | The request to run, in English |
Scripts
A named sequence of exact commands, run with sharknx <name> or sharknx run <name>.
cli:
scripts:
- name: secure house
aka: [lock down]
lines:
- "connect"
- "write 1/0/1 off"
- "write 1/0/2 off"
note: nightly shutdown
| Field | Required | Description |
|---|---|---|
lines |
Yes | Exact commands, one per line, without the sharknx word - see Assistant Commands |
- Lines run one after another, like commands joined with
;: a line still runs if an earlier one failed. Use&&,||, or|inside a line for dependencies. - Addresses must be literal - a script never uses project names or aliases.
- A script can't run another script.
- A script's
nameandakacan't be a built-in command:help,connect,disconnect,discover,write,read,monitor,ping,restart,progmode,scan,progscan,project,ip, orrun.
Complete example
version: 1
prompt:
entities:
- name: kitchen island lights
aka: [island]
address: 1/0/12
dpt: "1.001"
groups:
- name: kitchen lights
members:
- ref: kitchen island lights
- 1/0/13
rooms:
- name: media room
aka: [cinema]
members:
- { address: 1/1/1, type: light }
- { address: 1/1/2, type: blind }
phrases:
- name: movie mode
expands_to: "turn kitchen lights off"
cli:
scripts:
- name: secure house
aka: [night shutdown]
lines:
- "write 1/0/12 off"
- "write 1/0/13 off"
Validation
SharKNX checks the whole file before importing anything and shows a report. Nothing is saved until you import a file with no errors.
| Errors - block the import | Warnings - import allowed |
|---|---|
Invalid YAML, a version other than 1, an unknown field |
An address not in the loaded project |
A missing required field, empty members or lines |
An alias with the same name as an item in the project (use override: true to make the alias win) |
| An invalid address | A script command that depends on the project, e.g. a datapoint type - it is checked again when the script runs |
A duplicate name or aka, a ref to a missing entity |
|
| A script line that isn't a valid command, or that runs another script | |
| A script named like a built-in command | |
| Aliases with no ETS project loaded |
Limits
| Limit | Value |
|---|---|
| File size | 256 KB |
| Aliases in one file | 500 |
| Scripts in one file | 200 |
Related
- Aliases and Scripts - create, import, and manage
- Assistant Commands - the command syntax used in scripts
- The SharKNX Assistant - how the assistant works
