Overview

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