All messages are JSON objects, and look as follows
The # key is always present, and contains the time (Unit timestamp in milliseconds) at which the message was created. All messages from the same module have strictly increasing timestamps, and will arrive in that order. The modules use a time server to keep their clocks synchronized with an accuracy of a few seconds.
The #c key contains the message type (channel).
The #d key contains the id of the device which created the message.
All other keys are specific to the message type.
A message can be up to about 1 kB in size.
Messages are submitted immediately. If the module loses its internet connection, messages are queued and transmitted later. The queue can store about 1 hour worth of messages. If the queue is full, the oldest messages are discarded.
The user selects a product on an external device, e.g. his own mobile phone, or a screen attached to the vending machine. Once he has paid, the server sends the following message to the machine:
The ID is optional. If provided, it must be a 16 digit hex sequence. It is best to use random IDs.
Upon reception, the machine releases the product with the indicated options (if any) to the customer, and replies with one of the following messages:
The ID mentioned in the vend message is repeated here. The messages indicate what was actually served (or failed to be served). Hence, the vend suceeded messages may be used for accounting purposes, while the vend failed messages may be used for servicing purposes.
In case the vend failed, the money should be returned to the customer.
Only one product release can be underway at a time. If multiple vend messages are sent within a short amount of time, the vend may fail.
When a user selects a product on a machine, the module sends a vend request to the server:
The id is a random (unique) hex sequence. The price is indicated in cents. If the user changes the selection, a new vend request message with the same ID will be sent, which updates the previous vend request.
Similarly, if the user changes the selection on the remote device, the server may send a similar vend request update to the machine. The server may also change the price, or the product name. The machine will update the product selection on its display (if any).
If the user cancels the vend on the machine, or the machine decides to cancel the vend after a timeout, the following message will be sent:
Similarly, the server may send a vend cancelled message to the machine to cancel the vend and reset the display on the machine.
Once the payment has been settled, the server sends a vend message to the machine, which releases the product. The procedure is exactly the same as with a remote vend.
A vend usually ends with either a vend succeeded, vend failed, or a vend cancelled message. However, in certain cases, a vend may simply be abandoned without sending any notification. If the server suddenly receives a new vend request from a machine, any previous vend requests from that machine should be considered cancelled.
Similarly, the server may start a new vend request without cancelling the old one. The server may also send a vend message to release a product, while a vend request with a different ID is active.
The server may even reopen a cancelled vend by sending vend request or vend messages with a previously used ID. The machine only keeps track of one vend session at a time.
If a user pays with cash, the machine will release the product, and send a vend succeeded or vend failed message with payment method cash to the server:
The machine will accept cash no matter how the vend was initiated. If the server sends a vend request with a price, and the user settles this price with cash, the machine will release the product.
If the user first puts coins into the machine, and then selects the item, the server may only receive a vend succeeded or vend failed message, without any prior vend request. This case is handled entirely by the machine, and the remote system is just notified of the vend for accounting purposes.
Similarly, if a user pays with a payment media (e.g. a student card), the machine will release the product, and send a vend succeeded or vend failed message with payment type media to the server:
The payment ID is the card number from 0 to 4294967294, and may be null.
The payment type is one of
User group, price list and discount group are numbers from 0 to 255, and may be null.
Discount is a number from -2.55 to 1.00 and denotes
As with cash payments, vend succeeded or vend failed messages may be sent without any prior vend requests.
If a user presents a payment media with insufficient credit, and tops up using cash, the payment list contains both a media and a cash entry:
The module maintains a product list. When the user selects a product, the product list is consulted for the product's name and price. If the product is not found, the price indicated by the VMC is used, and the product has no name.
The following message clears the product list:
The following message adds or replaces a product on the list:
If a product with the same number exists on the list, the corresponding entry is replaced.
The following message requests the module to send the product list:
The module responds by sending all products.
The following message configures the display if the machine is idle:
Line-breaking is applied automatically. The alignment can be left, center (default), or right. HH:MM is replaced by the time.
Up to 8 texts can be configured with a duration (in seconds). These texts are rotated in the order provided.
When a product is selected, the idle screen is replaced by the product name and price, and the inserted coins.
The following message shows a short text on the VMC's display:
The duration is indicated in seconds, and rounded to the nearest 0.1 seconds. The message may be removed earlier, e.g. if a customer selects a product.
Line-breaking is applied automatically. The alignment can be left, center (default), or right.
For regular vends, coin collection and dispensing are managed automatically. However, coins can also be dispensed remotely by sending the following message:
The module has two operation modes:
Normal operation: The module is communicating with the VMC, and ready to process orders. In normal operation mode, the green LED shortly blinks once per minute.
Maintenance mode: The module is about to be initialized, configured, updated, or experienced an unexpected problem in normal mode. In this mode, the module does not communicate with the VMC, and cannot process orders. It can however be reconfigured, or update the firmware. In maintenance mode, the blue LED blinks once every 10 seconds.
When the module is powered on, it boots into maintenance mode, carries out a brief hardware check, and then boots into normal operation mode. This takes about 2 seconds.
The module reboots into maintenance mode in the following cases:
When in maintenance mode, the module reboots into normal operation mode in one of the following cases:
Upon restart, the module tries to connect to a WIFI network. It keeps trying every 10 seconds until it manages to connect to a network. If it loses a connection, it keeps trying to connect again. While trying to connect, the green (normal mode) or blue (maintenance mode) LED blinks about once per second. Blinking stops as soon as a connection is established.
The WIFI networks can be configured with the following message:
Up to 6 networks can be configured. The module tries to connect to them in the order they appear. If a network is not available, or the connection fails, the module gives up after 10 seconds and tries the next network. Once all networks have been tried, it starts from the top of the list.
Note that after receiving a new WIFI configuration, the module remains connected to the current network. To force reconnecting, reboot the module.
To retrieve the list of configured networks, send the following message:
If the module cannot connect to any configured WIFI network, it is unable to receive messages to reconfigure the WIFI networks. In this case, the WIFI can be reset and configured as follows:
The module will disconnect from the current WIFI network (if necessary), and connect to the hotspot. The module can then be configured through its web interface (http://setup.local), or receive configuration messages from the server.
Once the module has been configured, switch back to normal mode by restarting the module.
The following request reports the current state of a machine:
http://vending.viereck.ch/machines/3c8a1f7c38ec0000/last
The result includes the last message of each of the machines sensors and parts. The state has the following structure:
A section is only present if the corresponding information is available. If a section is not available, this may mean that the corresponding sensor or part is not available (e.g. no changer attached) or has not sent any update for a while.
The # number is the Unix timestamp of the information. Sensor values are typically updated every few minutes, while general information about the machine are updated infrequently.
The voltage of the MDB bus is reported as follows:
It is somewhere between 24 V and 30 V. The sensor has an accuracy of about ±2 V, and a precision well below ±0.1 V. It records about 300 values, and reports its median as well as a histogram (h). Voltage variations of about 1 V are normal.
Temperature and relative humidity are reported as follows:
t is the temperature of the electronic board in degrees Celsius. Since various components on the board are producing heat, the reported temperature is about 3-5 degrees above the ambient temperature.
rh is the relative humidity from 0 (0 %RH) to 1 (100 %RH).
The ambient noise level is reported as follows:
In a quiet environment, the noise level is about 9.
Values are in the range from 0 to 65536. A quiet place will report values below 1000. A loud noise is a value significantly above the baseline. If a machine is located in a noisy place, the baseline may be above 1000.
Motion is reported as follows:
For every axis, the average and variance is reported.
The average can be used to determine the orientation of the module with respect to the earth gravitational field. When mounted normally, the Y axis reports an average of about 4200 (1 G), while the other two axes are close to zero.
The variance is the vibration energy, and therefore denotes how much the board is moving along this axis. The sum of the three variances is the total motion energy.
Under normal conditions, the variance (energy) of all three axes remains below 100.
Incidents are often recorded by both the noise sensor and the motion sensor. The noise sensor picks up audible frequences from about 50 Hz to 20000 Hz, while the motion sensor picks up low frequencies from about 0.5 Hz to 5 Hz.
Information about the vending machine is reported as follows:
This information is reported by the vending machine. The feature level must be 3 to work with the K-vending module.
The uptime (number of seconds since reboot) is reported as follows:
The uptime can be used to detect module restarts.
Information about the wifi connection is reported as follows:
The wifi record reports to which network the module is connected.
The rssi record reports the signal strength. This is a negative value between approximately -100 (very bad connection) and -20 (very good connection). Values below -80 are of concern, since the network connection may drop intermittently.
If a LTE router is used, the following information is reported:
The wan section contains information about the LTE connection to the operator. A RSSI of 50 is very good, while 20 is bad.
The lan section contains information about the local network.
The devices list reports connected devices with their IP address and connection time.
If a coin changer is attached, the following information is reported:
Manufacturer, serial, model and software version are reported by the changer when the machine starts. Some changers support additional features, which are reported as bitmask. None of these features are required.
The changer status should be [3, 0]. Any other status denotes an error. Error codes are defined in the changer documentation.
The tubes list reports the amount of coins left. Every entry contains a tube index, the coin value stored in that tube, and the amount of coins remaining. Different tubes may have the same coin value. The coin count is reported as measured by the coin dispenser, and is usually accurate to ±2 coins.
When customers pay with coins, they either go into the tubes, or into a coin box. Only the coins in the tubes are reported, and only these coins are available for dispensing.
Information about cashless devices attached to the K-vending master is reported as follows:
The MDB protocol foresees two cashless devices with addresses 0x10 and 0x60. If only one device is attached, it may use any of the two addresses, but will always use the same.
In normal mode, the module sends information about its firmware:
Of interest is primarily the software build version.
In maintenance mode, the module sends information about its boot firmware, the flash size, and the available partitions:
To figure out whether the module is in maintenance mode, compare the timestamps (#) of the normal mode and maintenance mode messages.
The module uses the following ports:
The SumUp Solo terminal uses the following subset of these ports:
All connections are initiated by the devices, and therefore outgoing.