Unified approach how to report hardware connected to PDM

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. History

Hardware connected to PDM is reported in some way from the beginning. During the years there were introduced two methods: V5 multi part and MDL2014. All those historical methods are internally converted to current method MDL2020.

2. Historical reporting methods

2.1. V5 multi part

This is oldest method introduced in time of PDM 5. It uses multiple mnemonics to carry out version of connected components. They are send with every message. This method was also used by very early PDMs form model row 7. Following mnemonics are used for component reporting:

  • VEM – modem version. Type is not transferred and must be inferred from version.

  • VEP – printer version. Type is not transferred and must be inferred from version.

  • ARV – card reader version. Type is not transferred and must be inferred from version.

  • VEH – card reader version. Type is not transferred and must be inferred from version.

2.2. MDL2014

Versions of all components are reported in status message as mnemonic MDL after PDM start. Format is following:

#<component_id>,<hardware_name>,<software_version>

with following components ids:

  • #0 – configuration

  • #1 – main board (CPU)

  • #2 – PDM (RTB firmware)

  • #3 – Modem

  • #4 – Printer 1

  • #5 – Printer 2

  • #6 – Card reader 1

  • #7 – Card reader 2

  • #8 – Coin selector (device)

  • #9 – Coin selector (configuration)

Example of whole MDL mnemonic (split to multiple lines for better readability):

MDL
#0,V1.00_crc36fb 2020.06.07 17:32,CFG 7.05.01.12
#1,M151600020E1 2MB/8MB,1C38FC9346
#2,PDM7,7.5.4.65
#3,M17520,0021E
#4,MCS4036,B.2
#6,Margento-SN:89899,2018010_103B_0001
#8,Kel860.13,v6
#9,WHM8S01.453,1978;

This format is used by firmware released before 2020-08-01.

3. MDL2020

This format was introduced be necessity to transfer more information then just hardware name and software version. The information transferred for each hardware may vary based on hardware type, nevertheless some parts are common for all hardware (see chapter 3.3.1). For this reason a JSON format has been chosen to stay more flexible to better mark each information type about hardware configuration. Both formats MDL2014 and MDL2020 are transferred in the same mnemonic name "MDL". It is easy to distinguish between both of them. MDL2014 always starts with character # and MDL2020 with character { (as it is JSON).

3.1. Meta data

For now are meta data (for MDL mnemonic) not supported and completely ignored. They are only specified for future use if they are needed. Currently Default values are always used.

Format MDL2020 introduces also meta data to carry some additional information about content. As the meta data part is considered everything under key @meta. Meta data part is optional. If it is not specified default values are used.

Example of MDL mnemonic
MDL{"@meta":{"op":"put"},"cpu":{"dev" …

3.1.1. Operation

Operation specifies what to do with this hardware report. Operation is specified within key op. Possible values are:

  • put – [default value] replace previous hardware report by this one.

  • add – add devices in this hardware report to previous ones stored in the database. If device already exists then its properties will be overwritten. It can be used for hot plug in or report split to multiple messages.

  • del – delete device specified in this report from database. It can be used for hot remove.

The complete hardware report is longer than 1kB and needs to be split to two messages.

Message 1
MDL{"@meta":{"op":"put"},"cpu": …
Message 2
MDL{"@meta":{"op":"add"},"modem": …

3.2. Supported devices

All devices are reported in one JSON object according flowing schema. First level is device purpose. Second level defines its properties from various aspects. Now we have two aspects. First is dev - physical device providing the function. Second aspect is cfg. It tells which configuration device have (if it supports it). In future is possible to add another aspects as it is shown in configuration example in chapter Configuration example. Individual objects are described in section Devices.

/** Complete hardware report object. */
interface PdmHardware {
	cpu: {
		dev: CpuDevice;
	};
	pdm: {
		dev: SmartDevice;
		cfg: PdmConfiguration;
	};
	modem: {
		dev: SmartDevice;
	};
	printer_1?: {
		dev: SmartDevice;
		cfg?: PrinterConfiguration;
	};
	printer_2?: {
		dev: SmartDevice;
		cfg?: PrinterConfiguration;
	};
	card_reader_1?: {
		dev: SmartDevice;
	};
	card_reader_2?: {
		dev: SmartDevice;
	};
	bna?: {
		dev: Device;
	};
	coin_selector?: {
		dev: SmartDevice;
		cfg?: Configuration;
	};
	display?: {
		dev: SmartDevice;
		cfg: Configuration;
	};
	sd_card?: {
		dev: SdCardDevice;
	};
	"Sven's board which increases charging current from solar panel and allows measurement of energy provided by solar panel and energy discharged from battery"?: {
		dev: Device;
	};
	"Sven's board for encryption and digital signature of payments which are going to be send to tax office in Slovenia in offline mode"?: {
		dev: SmartDevice,
		cfg: Configuration
	};
}

Some devices are optionally present. Missing object key means that the device is not preset.

3.3. Device and Configuration Item variants

There are two types of reports: Device and Configuration. See appropriate chapters to find out more.

3.3.1. Devices

Device

Device abstraction represents any device connected to the PDM. Typical device of this class is simple device without firmware accessible from outside.

/** Basic device. */
interface Device {
	/** Name of physical device */
	name: string;
	/** Serial number (if exits) */
	sn?: string;
}
Example
{"name": "Sven's board", "sn": "1234"}

3.3.2. Smart Device

Extended version of device. This kind of device has it’s own firmware which provide some functionality. Updating the firmware can change its behavior. Firmware can be changed either locally or remotely.

/** Device with software part. */
interface SmartDevice extends Device {
	/** Version of firmware (if exists) */
	ver?: string;
	/** Updatable from PDM.control (remotely). Not provided = true.  */
	up?: boolean;
}
Example
{"name": "M17520", "ver": "0021E", "up": true}
Main board (CPU)

In addition to common parts, CPU has following properties.

/** Main board, CPU */
interface CpuDevice extends Device {
	/** RAM capacity in megabytes. */
	ram: number;
	/** ROM capacity in megabytes */
	rom: number;
}
Example
{"name": "M151600020E1", "sn": "1C38FC9346", "ram": 2, "rom": 8}
SD card

SD card in PDM’s slot.

interface SdCardDevice extends Device {
	type?: 'SD' | 'HC' | 'XC' | 'UC';
	/** capacity in megabytes. */
	capacity?: number;
}
Example
{"name": "SanDisk", "sn": "123456789", "type": "SD", "capacity": 2}
Display

Display element has no special type, just instance of Smart Device (see chapter Device and Configuration Item variants). Nevertheless we have now 4 displays. Some of them support firmware update, some of them not. Therefore special care is needed to indicate properly update possibilities. Example content follows. Put correct product names in hw field.

  • MCS Black and white: {"name":"MCS (BW)", "up":false}

  • MCS Color: {"name":"MCS (Color)", "up":false}

  • RTB Frank: "name":"Frank #1", "sw":"1.1", "sn":"123456789", "up":true}

  • RTB Sven: {"name":"Sven #1", "sw":"3.5", "sn":"987654321", "up":true}

3.3.3. Configurations

Configuration

Common part which is required for every configurations report.

/** Basic configuration report. */
interface Configuration {
	/** Name of logical device. */
	name: string;
	/** Version of configuration or user's description.	 */
	ver: string;
	/** Updatable from PDM.control (remotely). Not provided = false.  */
	up?: boolean
}

3.3.4. PDM Configuration

Adds information specific to configuration file.

/** Main configuration of PDM generated by PDM.config */
interface PdmConfiguration extends Configuration {
	/** Control Redundancy Check of original configuration file. */
	crc: string;
	/**
	 * Software which created this configuration file.
	 * It may be application name (and version) or some arbitrary name.
	 * E.g. 'PDM.config 7.1.2.3' or just '7.1.2.3' because we have only PDM.config.
	 */
	creator: string;
	/** Format of configuration file. More then 10 last years it is 1.00 */
	format: string;
}
Notes

  • Filed hw is always “PDM7” until we start new generation.

  • Filed sw is file creation date and time in ISO format until we introduce some versioning concept.

Example
{
	"name": "PDM7",
	"ver":"2020-06-15T10:09",
	"up": true,
	"crc":"A1B2",
	"creator":"7.1.2.3",
	"format":"1.00"
}
Printer configuration (fonts and logos)

Adds information about installed fonts and logos and their order.

/** Configuration of printer. Only new printer can report installed fonts and logos. */
interface PrinterConfiguration extends Configuration {
	/** Installed fonts */
	fonts?: Array<string>;
	/** Installed logos */
	logos?: Array<string>;
}
Example
{
	"name": "MCS4036",
	"ver": "RTB_WEu_01.07",
	"up": true,
	"fonts":[
		"RTB_WEU_1.0_normal",
		"RTB_WEU_1.0_italic",
		"RTB_WEU_1.0_bold",
		"RTB_WEU_1.0_italic+bold",
		"RTB_EEU_1.1_normal",
		"Arial_CE_1.0_normal"
	],
	"logos":[
		"Town logo",
		"Landesgartenschau",
		"Ad Mc'Donald",
		"Ad Burger King"
	]
}

3.3.5. Device and configuration concept

Some devices requires not only firmware but also configuration for proper function. In this case is one physical device represented by two logical devices: one with suffix _dev and the other with suffix _cfg.

It is important to correctly set device name (filed name) in this case.

Version independent configuration

If all configuration are interchangeable and works with all versions use the same name for device and configuration.

Printer type is MCS4036 and the configuration works with all its versions set the name also MCS4036. "printer_1":

{
	"dev": { "hw":"MCS4036", "sw":"B2", "sn":"1A2B3C", "up":true},
	"cfg": { "hw":"MCS4036", "sw":"Büren 1.0", "up":true, "fonts":[], "logos":[]}
}

Field sw is customer versioning tag.

Version dependent configuration

If configuration is version specific then the device name has to differentiate between those versions e.g. putting version to device name.

Example: Coin selector of type Kel860.13 has two (from configuration point of view) incompatible configurations (v6 and v7). In this case the physical device Kel860.13 has to report two logical devices like this.

V6
"coin_selector":{
	"dev":{"hw":"Kel860.13", "sw":"v6", "up":false},
	"cfg":{"hw":"Kel860.13_v6", "sw":"WHM8S01.453, 1978", "up":true}
}
V7
"coin_selector":{
	"dev":{"hw":"Kel860.13", "sw":"v7", "up":false},
	"cfg":{"hw":"Kel860.13_v7", "sw":"WHM8S01.449, 1976", "up":false}
}

3.4. Configuration example

{
	// Required content
	"cpu": {
		"dev": {
			"name": "M151600020E1",
			"sn": "1C38FC9346",
			"ram": 2,
			"rom": 8
		}
	},
	"pdm": {
		"dev": {
			"name": "PDM7",
			"ver": "7.5.150.3"
		},
		"cfg": {
			// If we have multiple versions in future there will be shown as
			// 'PDM7', 'PDM7_Frank', 'PDM8', ...
			"name": "PDM7",
			"ver": "2020-06-17T18:18",
			"crc": "abcd",
			"creator": "7.1.5.0",
			"format": "1.00"
		}
	},
	"modem": {
		"dev": {
			"name": "M17520-LTE",
			"ver": "0021E"
		}
	},
	// Optional content
	"printer_1": {
		"dev": {
			"name": "MCS4036",
			"ver": "B.2",
			// 4037 support SN
			"sn": "10000084-88105"
		},
		"cfg": {
			"name": "MCS4036",
			// 4037 use one of RTB set (fonts + logos)
			"ver": "RTB_WEu_01.07",
			// Ordered list of fonts in printer
			"fonts": [
				"RTB_WEU_1.0_normal",
				"RTB_EEU_1.1_normal",
				"Arial_CE_1.0_normal"
			],
			// Ordered list of logos in printer
			"logos": [
				"Town logo",
				"Landesgartenschau",
				"Ad Mc'Donald",
				"Ad Burger King"
			]
		}
	},
	"printer_2": {
		"dev": {
			"name": "MCS4036",
			"ver": "B.2",
			// 4037 support SN
			"sn": "10000084-88105"
		},
		"cfg": {
			"name": "MCS4036",
			// 4037 use one of RTB set (fonts + logos)
			"ver": "RTB_WEu_01.07",
			// Ordered list of fonts in printer
			"fonts": [
				"RTB_WEU_1.0_normal",
				"RTB_WEU_1.0_bold",
				"RTB_WEU_1.0_italic",
				"RTB_WEU_1.0_bold+italic"
			],
			// Ordered list of logos in printer
			"logos": [
				"Bus company logo",
				"Ad coffee shop",
				"Ad restaurant"
			]
		}
	},
	"card_reader_1": {
		"dev": {
			"name": "Ingenico I3",
			"ver": "CB2_0154A",
			"sn": "10000084-88105",
			"up": false
		},
		// Example of future extension possibility.
		"cfg": {
			"dev": "Ingenico",
			"ver": "12.34.",
			"up": false,
			"terminal": "123456",
			"bank": "Česká spořitelna"
		}
	},
	"card_reader_2": {
		"dev": {
			"name": "Ingenico I3",
			"ver": "CB2_0154A",
			"sn": "10000084-88105",
			"up": false
		}
	},
	"bna": {
		"dev": {
			"name": "MSM32001"
		}
	},
	"coin_selector": {
		"dev": {
			"name": "Kel860.13",
			"ver": "v6",
			"up": false
		},
		"cfg": {
			"name": "Kel860.13 v6",
			"ver": "WHM8S01.453 1978"
		}
	},
	"sd_card": {
		"dev": {
			"name": "SanDisk",
			"type": "SD",
			"capacity": 2097152
		}
	},
	"display": {
		// Display of model name '中華人民共和國' which can run different application. Produces firmware has version '1.3'.
		"platform": {
			"name": "中華人民共和國",
			"ver": "1.3",
			"sn": "ABC123"
		},
		// Frank's application with name 'Frank #1' of version '17.3.168.536'
		"dev": {
			"name": "Frank #1",
			"ver": "17.3.168.536"
		}
	},
	"Sven's board which increases charging current from solar panel and allows measurement of energy provided by solar panel and energy discharged from battery": {
		"dev": {
			"name": "Sven #1"
		}
	},
	"Sven's board for encryption and digital signature of payments which are going to be send to tax office in Slovenia in offline mode": {
		"dev": {
			"name": "Sven #2",
			"sn": "ABC123",
			"ver": "Sven@RTB 1.03"
		},
		"cfg": {
			"name": "Sven #2",
			"ver": "Ljubljana 1.00",
			// Example content
			"keys": [
				{
					"name": "Company1",
					"algorithm": "RSA",
					"length": 4096,
					"validFrom": "2010-09-22T13:22:02",
					"validTo": "2030-09-22T13:22:02"
				}
			]
		}
	}
}

4. Hardware run time information

New part of hardware reports is hardware run time information which reports current state. For transferring such an information the mnemonic SDL is used. The logic is the same as for MDL. First level of JSON structure defines the component and assigned object defines its properties.

There is no fixed fields yet in the properties (like they are for MDL see chapter Device and Configuration Item variants). PDM is free to use any valid JSON. It is also possible to use meta data described in chapter Meta data.