Besides plain English, the SharKNX assistant accepts exact commands that start with sharknx. An exact command is parsed, never interpreted: it does exactly what it says, or it is refused with the reason. It never guesses a command, a target, or a value.
Type sharknx help in the assistant for the list of commands, or sharknx help <command> for one command's usage. The Commands tab in the assistant's Help shows the same list.
Rules
sharknxcan be written in any case; command words must be exact.- Targets are literal addresses - group addresses as
main/middle/sub(1/2/3), devices asarea.line.device(1.1.5), lines asarea.line(1.1), gateways as an IPv4 address ormulticast. Project names and aliases are not used in exact commands. - A mistyped command may get a suggestion, but the suggestion only runs if you send it.
- Confirmation, connection checks, and plan limits apply as for any other request.
Commands
| Command | Does |
|---|---|
sharknx help [<command>] |
Shows all commands, or one command's usage |
sharknx connect [<ip>|multicast] |
Connects to the selected gateway, or to the given IP address or multicast routing |
sharknx disconnect |
Disconnects the gateway |
sharknx discover |
Searches the network for gateways |
sharknx write <ga> <value> [--dpt <main.sub>] |
Writes one value - see Values |
sharknx write [<ga>,...] [<value>,...] |
Writes a list of values to a list of group addresses, in order - both lists the same length |
sharknx read <ga> |
Reads a group address and shows the answer |
sharknx monitor start|stop|restart|status |
Controls or checks the group monitor |
sharknx ping <ia> |
Checks that a device answers |
sharknx restart <ia> |
Restarts a device |
sharknx progmode <ia> [on|off] |
Switches a device's programming mode - toggles it, or sets it on or off |
sharknx scan <area.line> |
Scans a line for devices |
sharknx progscan |
Finds devices in programming mode |
sharknx project |
Shows the loaded project's details |
sharknx ip |
Shows this device's IP address |
sharknx run <script> [-y] |
Runs a saved script - sharknx <script> does the same |
Scripts are saved with aliases and scripts. A built-in command name always wins over a script name.
Values
write takes the value in one of these forms:
| Form | Example | Means |
|---|---|---|
| Number | 50, 21.5, -10 |
The value in the datapoint type's unit - for DPT 5.001, 50 is 50 %. Write it without %. |
| Word | on, off, comfort |
A value name for the datapoint type. on and off work without a project. |
| Quoted value | "14:30", "255,0,0" |
A value made of several parts, such as a time, date, or colour |
| Hex | 0x0AFF |
Raw bytes, most significant first, sent as they are |
The datapoint type comes from the loaded ETS project. Without a project, or to use a different one, add --dpt, for example --dpt 9.001. A quoted value always needs a known datapoint type.
A few datapoint types use a two-word value:
| DPT | Values |
|---|---|
| 2.001 switch control | control on, control off |
| 3.007 / 3.008 dimming, blinds | up 1 … up 7, down 1 … down 7, stop |
| 18.001 scene control | recall 0 … recall 63, save 0 … save 63 |
Examples
| DPT | Command |
|---|---|
| 1.001 switch | sharknx write 1/2/3 on |
| 3.007 dimming | sharknx write 1/2/3 up 3 --dpt 3.007 |
| 5.001 percentage | sharknx write 1/2/3 50 --dpt 5.001 |
| 9.001 temperature | sharknx write 1/2/3 21.5 --dpt 9.001 |
| 10.001 time of day | sharknx write 1/2/3 "14:30:00" --dpt 10.001 |
| 11.001 date | sharknx write 1/2/3 "2026-07-10" --dpt 11.001 |
| 16.000 text | sharknx write 1/2/3 "hello" --dpt 16.000 |
| 17.001 scene number | sharknx write 1/2/3 5 --dpt 17.001 |
| 18.001 scene control | sharknx write 1/2/3 recall 5 --dpt 18.001 |
| 20.102 HVAC mode | sharknx write 1/2/3 comfort --dpt 20.102 |
| 232.600 RGB colour | sharknx write 1/2/3 "255,0,0" --dpt 232.600 |
| 251.600 RGBW colour | sharknx write 1/2/3 "255,0,128,64" --dpt 251.600 |
Leave out --dpt when the project already gives the group address that datapoint type. Supported datapoint types are listed in Supported DPTs.
Chaining commands
Join commands in one message to build a plan:
| Connector | Runs the next command |
|---|---|
; |
After this one finishes, whatever the result |
&& |
Only if this one succeeds |
|| |
Only if this one fails |
| |
If this one succeeds, passing its result on |
sharknx connect && monitor start
sharknx connect && write 1/2/3 21.5 ; write 1/2/4 22.0
sharknx is written once, at the start. If connect fails, nothing after it runs. sharknx monitor restart is the same as monitor stop && monitor start.
Passing a value on
Only read passes a value. The command after | is a write without a value - it writes the value that was read:
sharknx read 1/2/3 | write 4/5/6
Conditions
After |, a step can run only if the value read meets a condition - if <op> <value> : <command>, where <op> is ==, !=, >, <, >=, or <=:
sharknx read 1/2/3 | if == on : write 4/5/6 off
sharknx read 0/0/1 | if > 22.5 : write 0/0/9 1 || write 0/0/9 0
The second example switches 0/0/9 on when 0/0/1 reads above 22.5, and off otherwise.
Skipping confirmations
-y (or --yes) skips ordinary confirmations in a plan or script:
- at the start -
sharknx -y connect && write 1/2/3 on- it applies to the whole plan; - after one step -
sharknx connect && write 1/2/3 on -y- it applies to that step only.
It doesn't work on a single command, and it never skips a strong confirmation: those steps are confirmed together before the plan starts.
Related
- Use the Assistant - plain-English requests
- Aliases and Scripts - save command sequences as scripts
- Alias and Script File Format - script syntax in files
- Limits - plan and request limits
