Help
Keep links up-to-date.
When moving, renaming .md files, or changing any title (e.g. command or broadcast name) try to search links on previous file/title in this file or any other and update them.
Describe all commands and broadcasts in the same manner
Before adding documentation on new command/broadcast or changing existing one, please refer to following templates
New commands template
command_name
Hub type: hub_types
Connection type: connection_type
Permissions: permissions
command_description
request:
Field | Type | Required | Description |
---|---|---|---|
field_name |
field_type |
is_required |
field_description |
response:
Field | Type | Required | Description |
---|---|---|---|
field_name |
field_type |
is_required |
field_description |
broadcasts:
Broadcast | Description |
---|---|
broadcast_name |
broadcast_description |
errors:
Code | Message | Data |
---|---|---|
error_code |
error_message |
error_data |
Examples
example_title
example_description
request:
{
"method": "`command_name`",
"id": "_ID_",
"params": {
...
}
}
response:
{
"error": null,
"id": "_ID_",
"result": {
...
}
}
broadcasts:
none
Command placeholders description:
-
command_name
- Name of command in formatprefix
.command
-
prefix
can be eitherhub
, orcloud
hub
prefix is used for commands that are sent to hubcloud
prefix is used for commands that are sent to NMA
-
command
can contain multiple components divided by dots (e.g.gateways.list
). Command should end with action component. For commands that get information, action can be:list
- if response can contain list of multiple elementsget
- if response will contain single element- ...
or if command changes something, action can be something like:
set
update
create
check
- ...
-
hub_types
- should be specified if command is hub specific. Multiple hub types can be specified. -
connection_type
- Connection type that is required for the command. One of the following:Phantom
|Portal
|UI
|O/P
-
permissions
- Required permissions to execute command in format: [RESOURCE: PERMISSION
] -
command_description
- Custom description of what command does and what is returned as the result of command execution -
field_name
- Fully qualified params or result field name. E.g.interfaces[].ipv4.mode
-
field_type
- Type of field valie:string
,int
,float
,bool
,enum
,object
,array
, ... -
is_required
- Either+
(required) or-
(optional, or can be ommitted under certain circumstances) -
field_description
- Custom description of field -
error_code
- Code from General error codes (e.g.-32500
) -
error_data
- Error code from one of error group tables (e.g.user.login.badpassword
) -
error_message
- Description(error message) from same tables (e.g.Bad password
) -
broadcast_name
- Name of broadcast, e.g.hub.favorite.added
-
link_to_docs
- Link to broadcast documentation, e.g.ui_broadcasts/#hubfavoriteadded
-
broadcast_description
- Custom description of broadcast -
example_title
- Short description of example -
example_description
- Long description of example if title is not enough
Notes
- Add examples that cover different business logic aspects
- Add broadcasts to examples when appropriate
- Broadcasts section in examples can be omitted if command is not supposed to send them
Properly formatted commands:
- hub.extensions.plugin.run
- hub.software.info.get
- hub.software.update.plan
- hub.software.update.execute
Note: feel free to modify this list
New broadcasts template
broadcast_name
command_description
initiators:
result:
Field | Type | Required | Description |
---|---|---|---|
field_name |
field_type |
is_required |
field_description |
operationId | string | + | Id of initiating command |
Examples
example_title
example_descritption
{
"id": "ui_broadcast",
"msg_subclass": "`broadcast_name`",
"result": {
...
}
}
Broadcast template placeholders description:
-
broadcast_name
- Name of broadcast in formatprefix
.broadcast
-
prefix
can be eitherhub
, orcloud
hub
prefix is used for broadcasts that are sent from hubcloud
prefix is used for commands that are sent from NMA
-
broadcast
can contain multiple components divided by dots (e.g.modes.notifications.removed
). Broadcast name should end with result component:added
removed
switched
- ...
or status component
progress
- ...
-
command_name
- name of command that initiated this broadcast -
link_to_docs
- Link to broadcast documentation, e.g.house_modes_manager/#hubmodesnotificationsremove
-
broadcast_description
- Custom description of what broadcast is telling about -
field_name
,field_type
,is_required
,field_description
- Refer to command placeholders description -
example_title
- Short description of example -
example_description
- Long description of example if title is not enough
Properly formatted broadcasts:
Note: feel free to modify this list