3.1. Dispenser

This section provides the API specifications for dispensers. It applies to

Toilet paper dispensers
Paper towel dispensers
Cotton towel dispensers
Soap dispensers
Lotion dispensers
Disinfectant dispensers

3.1.1. Definitions

Common definitions

3.1.1.1. Dispenser Generic Definitions

Dispenser

A device that provides access to a consumer good: The soap in a washroom is provided through a soap dispenser

Dispenser Category

The type of consumer good accessed through the dispenser

toilet paper
paper towel
cotton towel
soap
disinfectant
lotion
room fragrance

Toilet Paper

Tissue-paper used in a toilet paper dispenser

Can differ in - rolled or folded - perforation - number of plies - paper count - diameter of the roll or height of the paper container

This toilet paper dispenser can hold 250 sheet of 3 plies paper

Paper Towel

Disposable tissue-paper for drying hands used in a towel dispenser

Can differ in - folded or rolled - number of plies - paper count - diameter of the rolled paper or height of the paper container

This dispensers contains multi-fold paper towels

Cotton Towel

Washable fabric towel for drying hands used in a towel dispenser: The cotton towel will be washed at the end of the roll

Soap

Liquid for washing hands used in a soap dispenser: The soap is very soft on my hands

Disinfectant

Liquid antimicrobial agent to disinfect hands used in a disinfect dispenser: This disinfectant kill 99.9% of the germs

Lotion

A low-viscosity topical preparation intended for application to the skin for medicinal or cosmetic purposes: Your skin is very dry. You should use a lotion to moisturize it

Room Fragrance

A chemical or molecules of fragrance introduced into the air of interior spaces to mask or eliminate unpleasant odors: A portion of the room fragrance will provide a fresh air for at least an hour

Chamber

Compartment of a dispenser holding a (none-liquid) consumable: This two-chambers toilet paper dispenser has a Left and right chamber

Bottle

Container for a liquid consumable (soap or disinfectant)

Can differ in

refillable/disposable
amount of soap/size/height

This soap bottle can hold 500 ml

Reservoir

Little tank inside a dispenser for liquid consumables that can hold a certain amount of the respective consumable from the bottle: The reservoir holds 160 portions

Portion

The minimum amount of consumable a user will get from a dispenser: A portion a soap is 0.4ml

Dispenser System

Device consisting of a housing, storage for the consumable, mechanism for dispensing the consumable and possibly other electronics and sensors: The CWS Paradise Foam NT is a non-touch soap dispenser system

Dispenser Filling Level

The remaining available consumable in a dispenser reported in percent: The soap dispenser has a filling level of 25% remaining soap

Dispenser Last Service

The last time the consumable of a dispenser was refilled: The toilet dispenser was last serviced an hour ago

Expected Next Service

The next estimated time the consumable of a dispenser should be refilled: The expected next service time to refill the soap dispenser is 8:00

3.1.2. Use cases

Note

Join FDS to get access to examples and use cases.

3.1.3. FDS compliance requirements

3.1.3.1. Object Model

3.1.3.1.1. Specification object for the dispenser device type

The device type in the generic device specification object must be
- “dispenser”
The device information provider must provide a specification object that contains a device_type_specific object defined in the following diagram

../../_images/dispenser_specification_object_model.png

The category must be one of:
- “toilet_paper”
- “paper_towel”
- “cotton_towel”
- “soap”
- “lotion”
- “disinfectant”
- “room_fragrance”

The detailed API specifications for each object can be found in the reference chapter.

3.1.3.1.2. Status object for the dispenser device type

the device information provider must provide a status object that contains a device_type_specific object defined in the following diagram

../../_images/dispenser_status_object_model.png

The detailed API specifications for each object can be found in the reference chapter.

3.1.3.1.3. Diagnostic object for the dispenser device type

the device information provider must provide a diagnostic object that contains a device_type_specific object defined in the following diagram

../../_images/dispenser_diagnostic_object_model.png

The detailed API specifications for each object can be found in the reference chapter.

3.1.3.1.4. Statistic object for the dispenser device type

Note

The Statistic object is not being defined for dispensers in FDS Version 2

3.1.3.2. Web API (Pull Model)

The device information provider must expose the specifications endpoint to get the list of available devices and their specifications

GET https://{Device Information Provider URL}/fds/v2/specifications

The device information provider must expose the statuses endpoint to get the latest status for one or multiple devices

GET https://{Device Information Provider URL}/fds/v2/statuses

The device information provider must expose the diagnostics endpoint to get the diagnostic for one or multiple devices

GET https://{Device Information Provider URL}/fds/v2/diagnostics

Note

The statistics endpoint to expose the statistics information is not being defined for dispensers in FDS Version 2

A call to:

GET https://{Device Information Provider URL}/fds/v2/statistics

must return an error object

{
    "status": 204,
    "message": "not_implemented"
}

The device information provider must expose the POST request on the tag endpoint to let a client application create a new tag

POST https://{Entity Information Provider URL}/fds/v2/tag

The device information provider must expose the GET request on the tag endpoint to provide the content of a tag

GET https://{Entity Information Provider URL}/fds/v2/tag

The device information provider must expose the DELETE request on the tag endpoint

DELETE https://{Entity Information Provider URL}/fds/v2/tag/<tag_id>

The device information provider must expose the PUT request on the tag/<tag_id>/entities endpoint

PUT https://{Entity Information Provider URL}/fds/v2/tag/<tag_id>/entities

The device information provider must expose the DELETE request on the tag/<tag_id>/entities endpoint

DELETE https://{Entity Information Provider URL}/fds/v2/tag/<tag_id>/entities

3.1.3.3. Publish/Subscribe (Push model)

3.1.3.3.1. Events

The device information provider must publish the following alerts and notifications

Message code	Description	Message category	Message code specific object
out_of_order	The device is out of order and needs service intervention	alert	out_of_order_details property - array of information provider codes
offline	The device is not communicating	notification	last_contact property

3.1.3.3.2. Publish status information

The following data must be published by the information provider

fds/v2/<subscriber_id>/<tag_id>/bin/<device_id>/status/filling_level

The payload must be:
- The filling_level object

3.1.3.3.3. Publish predictive and prognostic information

The following data must be published by the information provider

fds/v2/<subscriber_id>/<tag_id>/bin/<device_id>/diagnostics/expected_next_service

The payload must be:
- The expected_next_service property