mirror of https://github.com/nymea/nymea.git
186 lines
11 KiB
Plaintext
186 lines
11 KiB
Plaintext
/*!
|
|
\page create-setupmethods.html
|
|
\title CreateMethods and SetupMethods
|
|
\brief This page describes how the setup and creation of a device is working in a plugin.
|
|
|
|
This page describes how the setup and creation of a device is working in a plugin. Since the device manager
|
|
handles all the plugins and devices there are certain steps during the device setup which have to be considered.
|
|
|
|
The \l{DeviceClass::CreateMethods}{CreateMethod} describes how the device will be created
|
|
(by the user, by discovery or automatically).
|
|
The \l{DeviceClass::SetupMethod}{SetupMethod} describes how the device will be set up. A \l{Device} can have
|
|
multiple \l{DeviceClass::CreateMethods}{CreateMethods}, but only one \l{DeviceClass::SetupMethod}{SetupMethod}.
|
|
|
|
\list
|
|
\li \l{DeviceClass::CreateMethods}{CreateMethods}
|
|
\list
|
|
\li \tt User \unicode{0x2192} \l{DeviceClass::CreateMethodUser}
|
|
\li \tt Discovery \unicode{0x2192} \l{DeviceClass::CreateMethodDiscovery}
|
|
\li \tt Auto \unicode{0x2192} \l{DeviceClass::CreateMethodAuto}
|
|
\endlist
|
|
\li \l{DeviceClass::SetupMethod}{SetupMethods}
|
|
\list
|
|
\li \tt JustAdd \unicode{0x2192} \l{DeviceClass::SetupMethodJustAdd}
|
|
\li \tt DisplayPin \unicode{0x2192} \l{DeviceClass::SetupMethodDisplayPin}
|
|
\li \tt EnterPin \unicode{0x2192} \l{DeviceClass::SetupMethodEnterPin}
|
|
\li \tt PushButton \unicode{0x2192} \l{DeviceClass::SetupMethodPushButton}
|
|
\endlist
|
|
\endlist
|
|
|
|
|
|
\section2 CreateMethod \b "User" - SetupMethod \b "JustAdd - synchronous"
|
|
|
|
This is the simplest setup what a device can have.
|
|
|
|
\list
|
|
\li CreateMethod \b "User": the user has to fill out the \l{Param}{Params} of the device by hand
|
|
\li SetupMethod \b "JustAdd": there is nothing special to do during the setup with the device.
|
|
\endlist
|
|
|
|
Once the is adding the device the \l{DeviceManager} is calling following methods in the device plugin:
|
|
|
|
\image setup-sync-resized.png
|
|
|
|
\list
|
|
\li \b Setup
|
|
\list
|
|
\li \b 1. | The main setup of the device in the plugin.
|
|
\li \b 2. | If something goes wrong during the setup return \l{DeviceManager::DeviceSetupStatusFailure}, otherwise \l{DeviceManager::DeviceSetupStatusSuccess}.
|
|
\li \b 3. | If the device setup succeeded and the device is in the system, the \l{DeviceManager} will call the \l{DevicePlugin::postSetupDevice()}{postSetupDevice()} method.
|
|
\endlist
|
|
\endlist
|
|
|
|
\section2 CreateMethod \b "User" - SetupMethod \b "JustAdd" - asynchronous
|
|
|
|
\image setup-async-resized.png
|
|
|
|
\list
|
|
\li \b Setup
|
|
\list
|
|
\li \b 1. | The main setup of the device in the plugin.
|
|
\li \b 2. | If the status can not be determined immediately, we have to tell the \l{DeviceManager} that the status will be communicated later.
|
|
\li \b 3. | Once the setup status is determined, the plugin can emit the signal \l{DevicePlugin::deviceSetupFinished} to inform the \l{DeviceManager} about the result.
|
|
\li \b 4. | If the device setup succeeded and the device is in the system, the \l{DeviceManager} will call the \l{DevicePlugin::postSetupDevice()}{postSetupDevice()} method.
|
|
\endlist
|
|
\endlist
|
|
|
|
\section2 CreateMethod \b "auto" - SetupMethod \b "justAdd"
|
|
|
|
\image setup-auto-resized.png
|
|
|
|
\list
|
|
\li \b Monitor
|
|
\list
|
|
\li \b 1. | The method \l{DevicePlugin::startMonitoringAutoDevices()}{startMonitoringAutoDevices()} will be called once the \l{DeviceManager} has loaded all \l{DevicePlugin}{Plugins} and the discovery for auto devices can be started.
|
|
\li \b 2. | Once the plugin has discovered one or more devices, the plugin can emit the signal \l{DevicePlugin::autoDevicesAppeared()} to inform the \l{DeviceManager} that new devices where found (without user interaction).
|
|
\endlist
|
|
\li \b Setup
|
|
\list
|
|
\li \b 3. | The plugin will be set up with the params of the auto discovered \l{DeviceDescriptor}.
|
|
\li \b 4. | If something goes wrong during the setup return \l{DeviceManager::DeviceSetupStatusFailure}, otherwise \l{DeviceManager::DeviceSetupStatusSuccess}.
|
|
\li \b 5. | If the device setup succeeded and the device is in the system, the \l{DeviceManager} will call the \l{DevicePlugin::postSetupDevice()}{postSetupDevice()} method.
|
|
\endlist
|
|
\endlist
|
|
|
|
|
|
\section2 CreateMethod \b "Discovery" - SetupMethod \b "JustAdd"
|
|
|
|
\image setup-discovery-resized.png
|
|
|
|
\list
|
|
\li \b Discovery
|
|
\list
|
|
\li \b 1. | The user started to discover devices. The method \l{DevicePlugin::discoverDevices()}{discoverDevices()} will be called in the plugin.
|
|
\li \b 2. | Return \l{Device::DeviceError}{DeviceErrorAsync} and start the discovery in the source code.
|
|
\li \b 3. | Once the discovery is finished, the plugin can emit the signal \l{DevicePlugin::devicesDiscovered} to inform the \l{DeviceManager} about the result.
|
|
\endlist
|
|
\li \b Setup
|
|
\list
|
|
\li \b 4. | The plugin will be set up with the params of the discovered \l{DeviceDescriptor}.
|
|
\li \b 5. | If something goes wrong during the setup return \l{DeviceManager::DeviceSetupStatusFailure}, otherwise \l{DeviceManager::DeviceSetupStatusSuccess}.
|
|
\li \b 6. | If the device setup succeeded and the device is in the system, the \l{DeviceManager} will call the \l{DevicePlugin::postSetupDevice()}{postSetupDevice()} method.
|
|
\endlist
|
|
\endlist
|
|
|
|
\section2 CreateMethod \b "Discovery" - SetupMethod \b "PushButton"
|
|
|
|
\image setup-discovery-pairing-resized.png
|
|
|
|
\list
|
|
\li \b Discovery
|
|
\list
|
|
\li \b 1. | The user started to discover devices. The method \l{DevicePlugin::discoverDevices()}{discoverDevices()} will be called in the plugin.
|
|
\li \b 2. | Return \l{Device::DeviceError}{DeviceErrorAsync} and start the discovery in the source code.
|
|
\li \b 3. | Once the discovery is finished, the plugin can emit the signal \l{DevicePlugin::devicesDiscovered} to inform the \l{DeviceManager} about the result.
|
|
\endlist
|
|
\li \b Pairing
|
|
\list
|
|
\li \b 4. | The user has already seen the pairing info with the push button instructions and should also already have pushed the button. The method \l{DevicePlugin::confirmPairing()} will be called. Here can be verified if the push button has been pressed and if the pairing succeeded.
|
|
\li \b 5. | Returns the \l{DeviceManager::DeviceSetupStatus} to inform about the result (sync or async).
|
|
\li \b 6. | Once the pairing has been verified (check if the button has been pushed) the plugin can emit the signal \l{DevicePlugin::pairingFinished()} to inform the \l{DeviceManager} about the result.
|
|
\endlist
|
|
\li \b Setup
|
|
\list
|
|
\li \b 7. | The plugin will be set up with the params of the paired \l{Device}.
|
|
\li \b 8. | If something goes wrong during the setup return \l{DeviceManager::DeviceSetupStatusFailure}, otherwise \l{DeviceManager::DeviceSetupStatusSuccess}.
|
|
\li \b 9. | If the device setup succeeded and the device is in the system, the \l{DeviceManager} will call the \l{DevicePlugin::postSetupDevice()}{postSetupDevice()} method.
|
|
\endlist
|
|
\endlist
|
|
|
|
\section2 CreateMethod \b "Discovery" - SetupMethod \b "EnterPin"
|
|
|
|
\image setup-discovery-pairing-resized.png
|
|
|
|
\list
|
|
\li \b Discovery
|
|
\list
|
|
\li \b 1. | The user started to discover devices. The method \l{DevicePlugin::discoverDevices()}{discoverDevices()} will be called in the plugin.
|
|
\li \b 2. | Return \l{Device::DeviceError}{DeviceErrorAsync} and start the discovery in the source code.
|
|
\li \b 3. | Once the discovery is finished, the plugin can emit the signal \l{DevicePlugin::devicesDiscovered} to inform the \l{DeviceManager} about the result.
|
|
\endlist
|
|
\li \b Pairing
|
|
\list
|
|
\li \b 4. | The user has already seen the pairing info with the instructions which pin should be entered. The method \l{DevicePlugin::confirmPairing()} will be called. Here can be verified if the entered pin is valid and if the pairing succeeded.
|
|
\li \b 5. | Returns the \l{DeviceManager::DeviceSetupStatus} to inform about the result (sync or async).
|
|
\li \b 6. | Once the pairing has been verified (check if the button has been pushed) the plugin can emit the signal \l{DevicePlugin::pairingFinished()} to inform the \l{DeviceManager} about the result.
|
|
\endlist
|
|
\li \b Setup
|
|
\list
|
|
\li \b 7. | The plugin will be set up with the params of the paired \l{Device}.
|
|
\li \b 8. | If something goes wrong during the setup return \l{DeviceManager::DeviceSetupStatusFailure}, otherwise \l{DeviceManager::DeviceSetupStatusSuccess}.
|
|
\li \b 9. | If the device setup succeeded and the device is in the system, the \l{DeviceManager} will call the \l{DevicePlugin::postSetupDevice()}{postSetupDevice()} method.
|
|
\endlist
|
|
\endlist
|
|
|
|
|
|
\section2 CreateMethod \b "Discovery" - SetupMethod \b "DisplayPin"
|
|
|
|
\image setup-discovery-display-pin-resized.png
|
|
|
|
\list
|
|
\li \b Discovery
|
|
\list
|
|
\li \b 1. | The user started to discover devices. The method \l{DevicePlugin::discoverDevices()}{discoverDevices()} will be called in the plugin.
|
|
\li \b 2. | Return \l{Device::DeviceError}{DeviceErrorAsync} and start the discovery in the source code.
|
|
\li \b 3. | Once the discovery is finished, the plugin can emit the signal \l{DevicePlugin::devicesDiscovered} to inform the \l{DeviceManager} about the result.
|
|
\endlist
|
|
\li \b{Display pin}
|
|
\list
|
|
\li \b 4. | Once the user selected one of the discovered devices the device manager will call the method \l{DevicePlugin::displayPin()} in the plugin. Here can be sent the command to display the pin on the device. The pin which will be displayed on the device will be passed as secret in the \l{DevicePlugin::confirmPairing()} method.
|
|
\li \b 5. | Returns the \l{Device::DeviceError} to inform about the result (sync or async).
|
|
\endlist
|
|
\li \b Pairing
|
|
\list
|
|
\li \b 6. | The user should see now the pin on the display and the pairing info. The method \l{DevicePlugin::confirmPairing()} will be called once he entered the pin. Here can be verified if the pin is authorized by the device and if the pairing succeeded.
|
|
\li \b 7. | Returns the \l{DeviceManager::DeviceSetupStatus} to inform about the result (sync or async).
|
|
\li \b 8. | Once the pairing has been verified (check if the button has been pushed) the plugin can emit the signal \l{DevicePlugin::pairingFinished()} to inform the \l{DeviceManager} about the result.
|
|
\endlist
|
|
\li \b Setup
|
|
\list
|
|
\li \b 9. | The plugin will be set up with the params (i.e. containing a \tt pin param) of the paired \l{Device}.
|
|
\li \b 10. | If something goes wrong during the setup return \l{DeviceManager::DeviceSetupStatusFailure}, otherwise \l{DeviceManager::DeviceSetupStatusSuccess}.
|
|
\li \b 11. | If the device setup succeeded and the device is in the system, the \l{DeviceManager} will call the \l{DevicePlugin::postSetupDevice()}{postSetupDevice()} method.
|
|
\endlist
|
|
\endlist
|
|
*/
|