Disclaimer

This document is only collection of author’s notes, experiences and point of views. It is not, in any meaning, either complete description of the topic nor official RTB documentation. It may be inaccurate, incomplete, obsolete, misleading or completely wrong. It may even cause loss of data or damage system integrity. It may not comply with company codex, values, presentation style or economic interests or may reveal company secrets.

As such, it is absolutely prohibited to distribute this document outside of RTB & Co. GmbH. Such an action may result into legal acts against both the sender and the company. It is only intended, after review of technical and presentational correctness and accuracy, to be used as an information source for official documentation.

Always contact documentation department for information about current presentation style and allowed formats before creating customer’s documentation.

1. Implementation

This feature is composed of several functions. Each described in its own chapter.

1.1. Configuration

User may define counters in UI. Each counter have name, current value and maximal value. Name has to be unique within a zone. If the user tries to create a counter with the same name as the existing one, PDM.control will report error.

Counter names are case-sensitive. E.g. bus, Bus and BUS are three different counters.

Maximal value of counter is only recommendation send to PDM. PDM.control has no power to enforce maximal value to PDM. It is up to PDM to respect this value. If PDM requested to increment of a counter which already reached maximal value, it will be incremented anyway and the current value will be higher than maximum. Counter is internally implemented by int32. After value 2,147,483,647 it starts to be negative end eventually it wraps around. Value -1 is reserved for invalid value. It will be discussed in chapter Counter incrementation.

The current (and also maximal) value of the counter is shared among all PDMs within the zone. If it is changed on PDM.control, all PDMs will get update by next request.

All counters are set to zero once a day.

PDM can update more than one counter by one function call. This can be useful for instance in following case. Operator wants to limit usage of parking area e.g. to 50 cars, 10 buses but not more than 50 vehicles in total. In such a case, the following counters can be defined.

  • car, 50

  • bus, 10

  • total, 50

PDM then increment either car or bus counter and total be selling each parking ticket. By this technique both vehicle types (car, bus) and total vehicle (total) can be tracked.

It would be also possible to add car and bus together in firmware to get total value. It is a valid approach if total's maximal value stays constant for very long time. Its change would require updating configuration (or firmware). However, definition of total counter gives operator flexibility to change maximal or current value any time.

1.2. Remote functions for PDM

Examples below shows only content of MRQ mnemonic related to current request. Keys can be unquoted unless they contain spaces or special characters. MRQ itself is array[]. The rest of the message is standard.

Standard PDM message
PSA10027;GAC00011;DTM2021-05-12T17:08:00;VER7.5.5.54;PID1C38FC9346;MRQ[...];...;CRC1234

1.2.1. Counter list

PDM may ask for list of counters with actual values using request number 28.

Request
List counters with current value (request)
{
    "REQ":28
};
Response

Complete list of existing counters with maximal and current value.

List counters with current value (response)
{
    "REQ":28,
    "counters":[
        {"name":"bus","max":10,"val":5},
        {"name":"car","max":50,"val":27},
        {"name":"total","max":50,"val":32}
  ]
}

1.2.2. Counter incrementation

PDM may increase any number of counters values within a single request. It may even increase their value about more than 1.

Although it should not be regular case, there is also left possibility to decrease counter value. It is enough to provide negative value to increment. See example below.

Request

PDM provides name of counters and increment as it is shown on example below. It is not necessary to provide counters which value should not been changed.

Name non-existing represents counter which is not defined in PDM.control. It will be handled a special way in the response.

Increment counter values (request)
{
    "REQ":29,
    "counters":[
        {"name":"bus","inc":-1},
        {"name":"car","inc":3},
        {"name":"total","inc":2},
        {"name":"non-existing","inc":5}
  ]
}
Response

As a response repeat PDM control counters found in request with new values. Please note that new 'current' value must not be equal 'previous' + 'increment'.

If PDM requests to increment a counter which is not defined on PDM.control, its max and val are reported as -1. See example below.

Increment counter values (response)
{
    "REQ":29,
    "counters":[
        {"name":"non-existing","max":-1,"val":-1},
        {"name":"bus","max":10, "val":4},
        {"name":"car","max":50,"val":30},
        {"name":"total","max":50,"val":34}
  ]
}

1.3. Automatic cleanup

Automatic cleanup of old data runs weekly every Saturday about 3 o’clock. Please be aware that exact time may be changed in the future.

Data to be cleaned:

  • Counter older than one week.