The PcnService interface controls and manages the People Counter devices that are connected to a gateway. Through the PcnService configuration options, the People Counter connectivity modes and the polling period for the In/Out counters may be defined.

Upon activation, the PcnService performs the following actions on each People Counter:

Retrieves and caches the PcnVersion information from each People Counter
Sets the People Counter date and time to match the gateway’s data
Enables counting and diagnostics on the People Counter
Resets all In and Out counts in the People Counters if the pcn.count.init.reset is enabled

On each count poll cycle, the PcnService performs the following:

Polls each configured People Counter and updates the cached PcnState objects (one per connected People Counter)
Raises a single PcnCountChangeEvent with all the updated PcnStates, if there is a count change of one or more of the People Counters since the previous poll period
Raises a PcnDigitalInputEvent with the updated PcnState, if there is a change of one or more People Counters digital inputs since the previous poll period

The PcnService listens for ClockEvents and updates the internal clock of each connected People Counter. The PcnService also listens for UsbEvents and reinitializes itself if the RS-485 connection that is used to communicate with the People Counters is lost.

PcnService API

When activated or updated, the PcnService interface reads its configuration parameters (stored in an XML configuration file; refer to javadocs at http://esf.eurotech.com/doc/ESF-API/v2.0.10/index.html for details) and tries to connect to the configured Passenger Counters once the transport (RS-485 or Ethernet) has been initialized.

PcnService then starts a constant polling loop cycle as defined by the PollingPeriod rate. In this loop, PcnService maintains a PcnState for each Passenger Counter, recording all the variables that represent the state of a PCN at the present time.

The main method that should be used to query the PCN state is PcnService.getLatestPcnStates(). This method returns a list of the PcnState as it corresponds to each Passenger Counter.

PcnState

PcnState defines the People Counter In/Out count information service as follows:

pcnAddress - address of the PCN
pcnVersion - version of the PCN
timestamp - date/time of the last refresh
initState - state of the initialization (if not, values are not accurate)
fetchedFields - metrics that have been acquired (i.e., counts, inputs, diagnostics)
inCount - current value of the In count
outCount - current value of the Out count
input0Level - if true, digital input 0 is active
input1Level - if true, digital input 1 is active
diagnostics - see documentation for decoding
replyErrorsCount - number of reply errors since last reset
commErrorsCount - number of communication errors since last reset

PcnAddress

PcnAddress represents the address of a PCN that is connected to a gateway. If the People Counter is connected via RS-485, the address is represented by an integer based on its position in the RS-485 bus. If the People Counter is connected via Ethernet, the address is represented by InetAddress.

PcnAddress details include the following:

type - RS485 or ETHERNET
rs485Address - address of the PCN on the RS485 bus
inetAddress - address of the PCN as an InetAddress
socket - socket opened for a PCN connected on ethernet
inputStream - the input stream associated to the socket
outputStream - the output stream associated to the socket

PcnVersion

PcnVersion represents the version of the PCN software parts as follows:

pcnAddress - address of the PCN
timestamp - date/time of the last refresh
kernelVersion - Linux kernel version
osVersion - operating system version
fpgaFirmwareVersion - FPGA firmware version
imgServerVersion - ImgServer version

PcnService Configuration

PcnService is an OSGi component and is configurable using the metatype XML configuration file. The configurable parameters are as follows:

pcn.connectivity - defines whether the People Counters are connected via RS-485 or Ethernet
pcn.count.polling.period - sets the polling period in seconds. With each poll, the PcnService reads the latest In and Out counts and digital input status, and caches them into memory. A polling period of 0 disables the PcnService.
pcn.count.init.reset - sets the default flag for resetting counters at PcnService startup, before the first poll
pcn.count.init.enable - sets the default flag for enabling the counting process at PcnService startup
pcn.init.diag.enable - sets the default flag for enabling diagnostics in the counters at PcnService startup
pcn.polling.count.enable - sets the default flag for enabling count polling
pcn.polling.inputs.enable - sets the default flag for enabling inputs polling
pcn.input0.function - configures the function of digital input 0. Valid values include:
- 0 - does nothing
- 1 - resets counters; pcn.polling.inputs.enable must be true
- 2 - enables/disables counting; pcn.polling.inputs.enable must be true
pcn.input1.function - same as input0
pcn.use.digital.output - sets the default flag for enabling digital output as a programmable output
pcn.led.intensity.auto - enables the automatic regulation of the LED indicators. If enabled, pcn.set.led.intensity is ignored.
pcn.set.led.intensity - sets the light intensity of LEDS. Valid values are 0 to 255 (maximum intensity). 0 leaves the value programmed in the PCN unchanged. A single value must be entered for each PCN using ‘;’ as a separator. If pcn.led.intensity.auto is true, this field is ignored.
pcn.snp.max.error.count - defines the maximum number of errors before declaring People Counter disabled

If pcn.connectivity=RS485, the following parameters are also configurable:

rs485.snp.addresses - defines the addresses of all People Counters present on the serial bus using ‘;’ as a separator. These addresses must match the Serial Addresses that are configured in the People Counter.
rs485.port - defines the serial port name (e.g., /dev/tty0) or path in the USB bus (e.g., 4-2)
rs485.baudRate - sets the baud rate of the serial connection
rs485.bitsPerWord - sets the number of bits per word (data bits) for the serial connection
rs485.stopBits - sets the stop bits for the serial connection
rs485.parity - sets the parity for the serial connection
rs485.timeout - sets the timeout when sending a command to a People Counter via RS-485
rs485.retry.count - sets the number of retries when sending a command to a People Counter via RS-485

If pcn.connectivity=ETHERNET, the following parameter is also configurable:

ethernet.snp.ip.addresses - defines the addresses of all People Counters present on Ethernet network using ‘;’ as a separator. These addresses must match the Ethernet IP Addresses that are configured in the People Counter.

PcnZoneManager Bundle

A standard application is available to manage scenarios where the PCNs are installed in buildings (e.g., shops, conference rooms, etc.). This application is represented by the bundle org.eclipse.kura.protocol.pcn2.zonemanager and utilizes the PcnService previously described.

The org.eclipse.kura.protocol.pcn2.zonemanager bundle exposes two services: PcnZoneManager and PcnReportPublisher.

PcnZoneManager Service

A zone defines an area in which one or several PCNs are installed to count the same event. For example, an application that manages the washroom in a public area defined by two zones: ladies and gentlemen. Each of these zones can have several doors supporting a PCN.

This service is responsible for collecting and aggregating the counts for each zone, updating a PcnZone. The data can be aggregated on different periods, an hour, day, week, or month, each represented by a specific object in the PcnZone. Each time a period limit is reached, the corresponding event is thrown and the PcnReportPublisher service publishes the corresponding data.

In each PcnZone, various thresholds may be defined on the In count, the Out count, and Time period. When a threshold is reached, an event is thrown that may be used by an external application. In the washroom example, an In count threshold event may be used to send a signal for the cleaning staff.

The PcnZoneManager service contains the following members:

zoneId - a string representing the name of the zone (e.g., "ladies") that will be used as the last part of the topic published
pcns - an ArrayList, comma-separated list, of the PCN identifiers that are associated to the zone. The PCN identifiers match the RS-485 or Ethernet ID of the corresponding PCN.
thresholdIn - the number of In passages before the zone InExceeded flag is set. If zero, no In count threshold tracking is performed.
thresholdOut - the number of out passages before the zone OutExceeded flag is set. If zero, no Out count threshold tracking is performed.
thresholdTime - the number of seconds before the zone TimeExceed flag is set. If zero, no time threshold tracking is performed.
zoneState - the ZoneState of the zone
zoneStateWithDiagnostics
zoneResetState
zoneThresholdState
zonePeriodStats
zoneHourlyStats
zoneDailyStats
zoneWeeklyStats
zoneMonthlyStats
isThresholdEventRaised - a flag indicating that a threshold has been reached

PcnReportPublisher Service

The PcnReportPublisher service is responsible for publishing the data that corresponds to a predefined event on the corresponding topic. The following events are managed:

PcnZoneStateChangedEvent - triggers the publication of ZoneState on topic counts. When enabled, this event is thrown each time a PCN value changes.
PcnZonePeriodEvent - triggers the publication of ZonePeriodStats on topic period
PcnZoneHourlyEvent - triggers the publication of ZoneHourlyStats on topic hour
PcnZoneDailyEvent - triggers the publication of ZoneDailyStats on topic day
PcnZoneWeeklyEvent - triggers the publication of ZoneWeeklyStats on topic week
PcnZoneMonthlyEvent - triggers the publication of ZoneMonthlyStats on topic month
PcnZoneResetEvent - triggers the publication of ZoneResetState on topic zone_reset when a reset has been received by the ZoneManager
PcnZoneThresholdReachedEvent - triggers the publication of ZoneThresholdState on topic threshold_reached when a predefined threshold has been reached