Welcome!

This is the main API documentation page for users to interact with the PiDome REST API. See PiDome.org

Resources

The resources use a data model that is supported by a set of client-side libraries that are made available on the files and libraries page.

name path methods description
AuthApiController
  • /auth/qr
  • /auth/tokens
  • /auth/service/login
  • /auth/service/logout
  • /auth/service/ua
  • /auth/tokens/{tokenId}
  • /auth/service/password/strength/{password}
  • GET POST
  • GET
  • POST
  • GET
  • GET
  • DELETE
  • GET
Controller for authorizations.
ClusterApiController
  • /cluster/host
  • GET
Controller for cluster actions.
DeviceBuilderController
  • /builder/create/{serverPackageId}
  • /builder/discovery/devices/{discoveredId}
  • /builder/packages/{package}/devices/{device}
  • POST
  • GET
  • GET
Controller for the device builder.
HardwareApiController
  • /hardware
  • /hardware/interface/{interface}
  • /hardware/type/{transport}
  • /hardware/interface/{interface}/{key}
  • /hardware/peripheral/{volatilePeripheralId}/drivers
  • /hardware/peripheral/{volatilePeripheralId}/stats
  • /hardware/peripheral/{volatilePeripheralId}/stop
  • /hardware/peripheral/{volatilePeripheralId}/settings/{driverDefinitionId}
  • /hardware/peripheral/{volatilePeripheralId}/start/{driverDefinitionId}
  • GET
  • GET
  • GET
  • GET
  • GET
  • GET
  • GET
  • GET
  • PUT
Controller for controlling and maintaining the configurations, adding and removing of peripherals to the system.
InstallerApiController
  • /installation/repositories
  • /installation/repositories/{id}
  • GET PUT
  • DELETE
Controller for all installation related REST actions.
ItemApiController
  • /items
  • /items/all
  • /items/discovered
  • /items/region
  • /items/all/region
  • /items/definitions/{itemType}
  • /items/discovered/{discoveredItemId}
  • /items/item/{itemDefinitionId}
  • /items/item/{itemId}
  • /items/discovered/{discoveredItemId}/{itemDefinitionId}
  • /items/item/{itemId}/definition
  • GET
  • GET
  • GET
  • GET
  • GET
  • GET
  • GET
  • POST
  • DELETE GET PATCH PUT
  • POST
  • GET
Controller for items available for the end user to interact with.
ModulesApiController
  • /modules
  • /modules/active
  • /modules/capabilities
  • /modules/discovery/options
  • /modules/module/start
  • /modules/type/{type}
  • /modules/module/{activeContainerId}/info
  • /modules/module/{activeContainerId}/stop
  • /modules/type/{type}/{transport}
  • /modules/module/{activeContainerId}/discovery/start
  • /modules/module/{activeContainerId}/discovery/stop
  • GET
  • GET
  • GET
  • GET
  • POST
  • GET
  • GET
  • GET
  • GET
  • PUT
  • GET
Controller for controlling and maintaining the configurations, adding and removing of modules on the system.
PersonApiController
  • /person
  • /person/{id}
  • GET PATCH POST
  • DELETE GET
Controller for the person API.
PremisesController
  • /premises
  • /premises/{premisesId}
  • /premises/{premisesId}/properties
  • /premises/{premisesId}/sections
  • /premises/{premisesId}/properties/{propertyId}
  • /premises/{premisesId}/sections/{sectionId}
  • /premises/{premisesId}/properties/{propertyId}/levels
  • /premises/{premisesId}/properties/{propertyId}/levels/{propertyLevelId}
  • /premises/{premisesId}/properties/{propertyId}/levels/{propertyLevelId}/sections
  • /premises/{premisesId}/properties/{propertyId}/levels/{propertyLevelId}/sections/{sectionId}
  • GET PATCH POST
  • DELETE GET
  • GET PATCH POST
  • GET PATCH POST
  • DELETE GET
  • DELETE GET
  • GET PATCH POST
  • DELETE GET POST
  • GET PATCH
  • DELETE GET
The controller for premises and properties.
SystemApiController
  • /system/discovery
  • /system/locale
  • /system/locales
  • /system/network
  • /system/export/database
  • POST
  • GET PUT
  • GET
  • GET
  • GET
Controller for system API's.
UserApiController
  • /users
  • /users/me
  • /users/me/password
  • /users/user/{id}
  • GET POST
  • GET
  • PATCH
  • DELETE GET PUT
API Controller for the UserLogin object.

Data Types

JSON

type description
ActiveModuleContainer A container for an active module. An active module container acts as a proxy between the actual module and the server. The implementation is responsible for providing correct Items to the server's Item handler and a proxy to provide to modules.
BaseItemCommand A command for an item.
BaseItemMethod The base for an item method to execute.
BooleanInput Checkbox to select a true or false value.
BooleanVisualType Constants for visualizing boolean values. This is heavily depending on the front-end implementation of a data control. If a front-end implementation does not support colors they will not be shown as such. These are just used for hinting.
CheckboxEnumInput A list of checkboxes implementing the Enum types for displaying. The select list only accepts unique objects. If you want to add same values you must initialize a new object to add. Use the setListValues and addItem methods to fill the list for presenting to the user.
CheckboxInput A list of checkboxes implementing the WebInputField types for displaying. The select list only accepts unique objects. If you want to add same values you must initialize a new object to add. Use the setListValues and addItem methods to fill the list for presenting to the user.
ClusterHost Class providing host information.
ClusterMode The modus of the cluster agent.
ColorpickerMode Enum for defining the color picker mode. This is just an hint for front-ends to be able to implement different color picker modes. For example a device only supporting a limited set of colors would use RGB. Devices with more granular control, for example a light fixture, could use HSB. Light fixtures capable of doing white tints could use kelvin.
ControlCommand A single control command to be used in command sets.
ControlCommandOfString A single control command to be used in command sets.
ControlCommandSet A set of commands for a control. Used in various controls where there are multiple commands able to be send such as the color picker and the select control.
ControlCommandSetOfString A set of commands for a control. Used in various controls where there are multiple commands able to be send such as the color picker and the select control.
ControlConfiguration Structure for custom composed devices when posted to the server.
ControlConfigurationInputType A control configuration input type.
ControlGraphType Graph types.
ControlListConfigurationItem A configuration for list items.
ControlStatus The status of a control.
ControlVisualType The visual type of a control. Using this helps a front-end to decide what kind of visual control type the control is. This is mainly used with data controls.
CustomSerialDevices Base device for serial interfaces which has been custom created by the user.
DataLink Data link for interchanging data between components.
DefinitionType The definition types.
DescriptionList HTML dl like equivalent.
DescriptionListItem HTML dt,dl equivalent. This class is useful for displaying name value pairs. It is constructed as as horizontal and not below each other and without indentation. Currently dd is limited to be only a text string.
DeviceBooleanDataControl A boolean data control.
DeviceBuilderConfiguration A configuration for the device builder.
DeviceBuilderType The device builder type. A device builder type determines if a builder via code, a file or database should be used.
DeviceButtonControl A simple button in the controls. When a button is pressed it will ALWAYS be honoured.
DeviceColorPickerControl The color picker control. The color picker is of complex type using an DeviceColorPickerControlColorData for it's value.
DeviceCommand A command to be executed by a device module.
DeviceControl The base definition of a control in a device.
DeviceControlDataType The data types inside a control.
DeviceControlGroup A group of device controls.
DeviceControlType Enum for identifying control types.
DeviceDefinition A definition of a device to be stored in the database and is re-creatable.
DeviceMeta A container for linking a device to it's definition.
DeviceNumberDataControl Number based data control.
DeviceOptions Device options.
DeviceParameter A device parameters. Device parameters are used by code, and can be set by code. When Device parameters are used in a discovered device, they will be included in the device created.
DeviceSelectControl The select control. The select control is an Integer list indexed based control. When you want the real data which is available on the selected value use getValueData
DeviceSliderControl The slider control. The slider control implements a Number type.
DeviceStringDataControl String based data control.
DeviceToggleControl The device toggle control.The toggle control is of a complex type. It's value contents is based on true or false control value. A true value contains a label and a value belonging to the internal true value. As same it is for false. The above results in when the toggle control is set to true, it is able to return a value of any type which is mapped to this true setting. If you only need to know if the value is true or false use getValue If you want to know which data is bound to the true state use getValueData.
DiscoveredDevice Information about a discovered device.With this class a user is presented a device in the discovered devices list.
DiscoveredItem A single discovered item.
DiscoveredItemDefinition An item defining a discovered item.
DiscoveryBroadcastMessage The message used for broadcasting.
DiscoveryPeriod Rule to be applied for periodic actions.
DiscoveryPeriodOptions Entity providing discovery options.
DisplayInput A display input is an unmodifiable text field. Use this "input" to provide the user with information which is unmodifiable. it consists of a label and a text.
DoubleInput Input field supporting decimals.
DriverDefinition A driver definition for an attached peripheral.
Future
FutureOfVoid
GeoLocation The current GEO Location.
HardwareComponent A base class to ensure compatibility with hardware methods. A hardware component is OS and hardware specific. A component on windows will not always be available on other platforms like raspberry pi pins are not available on for example desktops, or at least not in the same form.
HardwareDriver The base for the hardware driver.

This is a live object. This means that you are capable of keeping state of your implementation between start and stop methods. Use the provided Promise's in the start and stop methods to indicate success or failure.

The Promise implementation used is provided by the Eclipse Vert.X project. Please check https://vertx.io/ for more information.

A driver has multiple phases:

  • Generate configuration phase during composeConfiguration.
  • Configure the driver and prepare any hardware to be used during configure
  • Start the driver and use the configuration set.
  • Stop the driver and release.

    The configure and startDriver methods are being executed after each other as long as the future of configure succeeds. When the configure fails, stopDriver will be called to release any references.

    The method stopDriver will always be called when there is some sort of failure or when the driver is being stopped. This IS the method to release all references.

    • HostIdentification The primary identification of an host.
    IconType Supported icon types.
    InputEnum Interface to be used by Enums which are being used by presentations.
    InputField Web component inputs fields.
    InputFieldType Possible field types for displaying.
    InputForm The input form containing sections with input fields.
    InputSection A section of controls.
    IntegerInput Input field for whole numbers.
    Interface The hardware interface of the component.
    IpAddressInput Input field for ip addresses.
    ItemAction An action for an item.
    ItemActionType The type of action for an item.
    ItemAddress The device address.
    ItemBooleanAddress A boolean based address.
    ItemCommand Base class for an item command.
    ItemDefinition A definition of a single item.
    ItemFloatAddress A float based address.
    ItemHexAddress A hex based address.
    ItemIntegerAddress A integer based address.
    ItemIpAddress Address based on ip address.
    ItemMeta Item Meta information.
    ItemOption A single item option.
    ItemPropertyInterface Interface for item option sets.
    ItemStringAddress A string based address.
    ItemType The item types identifiable for the server.
    Length Length used in the rule.
    LoginObject A simple login object which can be used to authenticate a user.
    LoginResource A login resource object.
    Manufacturer A manufacturer of an item or other component used.
    Maven2Repository A maven repository type. This type provides searching and gethering packages from maven repositories. It supports both normal and snapshot repositories. There is a naming convention to follow which can be identified at:
    MobileDevice A mobile device bound to an user.
    ModuleBase Minimal lowest base class for modules.
    ModuleCapabilities Capabilities set for modules.
    ModuleConfigurator Base class for a configurator.

    A configurator is an instance of the InputForm. A configurator is used when a module requires a configuration to be set when it is needed to be started. Special methods are added to the configurator which allows you to make calls to your module without the need to start it.
    A good example are plugins which are able to perform discovery and a user has to make a choice of an item that has been found during the discovery. Or when a user needs to supply an API key and there is a need to check in advance if the API key is suitable.
    Currently the methods are limited, but will more will be added over time.

    The depends on the module needs for a module to work correctly, not for the transport that is set to be used. For example if a serial driver is used the configuration of the serial parameters is already being taken care of by the serial driver.

    If for example a network based transport needs for example an API key, you would create a configuration requesting the APi key. The transport over the network is handled by the driver. Well, not the transport, but there will be a security manager being configured.

    ModuleDefinition This class provides a module candidate for which a configuration can be loaded.
    ModuleLoaderConfiguration Main object containing all the required information to start a module. When a module is started successfully a configuration is stored to create a persistence object to survive between restarts.
    ModuleNullConfiguration A null configurator for modules not requiring a configuration.
    ModuleType The available module types.
    NetInterface A network interface.
    NetworkDataLink The link between a network and an implementation module.
    NetworkDevice A single network interface identifying device.
    NetworkDevices Provider of network devices.
    Number
    ObjectPropertyBinding A property binding bean for typed objects.
    PassChangeObject Object used for password changes.
    PasswordInput Password text input field.
    PasswordStrengthResponse Password strength response object.
    Peripheral A to PiDome attached device.
    Person Identifying a person.
    PidomeAuthToken The token used in the authentication of a request on behalf of a user. This is more then just the token. This object supplies the end user extra context about an token where applicable. This will support the end user in revoking tokens. Great care should be taken by API development. The return of tokens should only be done by the end user which owns these.
    PlatformInfo Identifying the platform running on.
    Premises The premises.
    PremisesSection A section on a premises.
    Presentation Base class for displating information on the frontend.
    PresentationComponent Presentation component types.
    PresentationIcon To display an icon.
    PresentationPlatform Enum describing the presentation targets.
    PresentationSection A basic section.
    Property A property (housing / building) The current meaning of property is housing, building on a premises. If looking for system based properties go to org.pidome.server.system.config.SystemConfig
    PropertyLevel A level in the premises. From basement to top floor/attic location.
    PropertySection A region on a premises level. From rooms, attics, toilets to a region in a garden, driveway or parking lot etc.
    PropertySectionType The type of section identifying where it is located.
    QrData The object holding the QR data. Object is required for completing the authorization process.
    RegionSection The base for any section. This entity contains two parameters which provides support to display this entity in an ordered manner with a combined compound name like:
    • premises/section
    • premises/property/level/section
    The above is only available when a compound request is made. For example when retrieving items. These two parameters are transitive and can not be set or altered as this will have no result.
    Repository A single remote repository.
    RepositoryContainer A provider for repositories. A repository provider is a collection of repositories where a package originates from. The provider can consist of multiple repositories which normally would contain normal and snapshot versions of a package.
    Role The user roles.
    SelectEnumInput A select list implementing the Enum types for displaying. The select list only accepts unique objects. If you want to add same values you must initialize a new object to add. Use the setListValues and addItem methods to fill the list for presenting to the user.
    SelectInput A select list implementing the WebInputField type fields. The select list only accepts unique objects. If you want to add same values you must initialize a new object to add. Use the setListValues and addItem methods to fill the list for presenting to the user.
    SerialDataLink A data link between serial consumers and producers.
    SerialDevice A device that communicates through the serial interface.
    SerialDevices Root class for serial based devices.
    ServerPackage A server package.
    ServerVersion The server version.
    ServicesConfig Class containing the configuration of the available services suitable for consuming.
    StringMultiLineInput Multi line text input field.
    StringSingleLineInput Single line text input field.
    SubSystem The sub system used to communicate with the peripheral.
    SubmittedForm Container for forms for the frontend. The target is implementation specific. When a PresentationForm is communicated with the outside world it is expected to be returned as the PresentationForm.
    SystemLocale A single system locale object.
    Type Types supported by discovery.
    USBDevice Creates an USB device.
    USBDevices Covering class for all USB actions.
    Unit The period unit.
    UnknownModule Fallback for incorrectly configured modules. Generic implementation is used to be able to trackback to the module that's wrongly configured. Future implementation of this module will be for development purposes.
    UrlInput An input field expecting an URL. URL as described as java.net.URL
    UsbHidDevice An USB HID device.
    UsbSerialDevice An USB device supporting a serial interface.
    UserLogin User model. (Database annotations)