How to Use People Counter

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.

Transportation Bundle

A standard application is available to manage scenarios where the PCNs are installed in transit vehicle (e.g. buses or trams). This application is represented by the bundle com.eurotech.pcn2.app.transportation and utilizes the PcnService previously described.

The bundle exposes the service Pcn2transportation.This service is very simple, it publishes the in and out counts of selectable events as they are read from the PCN and can optionally publish the aggregate counts for a vehicle.

Pcn2Transportation configuration

publishTopic.rawData: this is the name of the topic where the raw data will be published. If it is left empty, nothing will be published.

metricName.rawInCount: define the name of the metric that will report the in counts for each PCN. This name will be appended with the address of the PCN. For example the metric name corresponding to the second PCN (PCN 2) in a serial installation could be in2 or for an Ethernet installation of the PCN, it will be in192.168.1.101.

metricName.rawOutCount: define the name of the metric that will report the out counts for each PCN. This name will be appended with the address of the PCN. For example the metric name corresponding to the second PCN (PCN 2) in a serial installation could be out2 or for an Ethernet installation of the PCN, it will be out192.168.1.101.

publish.onAnyCountChange: if true, the counts will be published everytime they change. This option can cause a large amount of data to be published and stored on the Cloud.

publish.onTimeInterval: if true, the counts will be published periodically.

publish.onDoorClosed: if true, the counts will be published every time the door is closed. This is only possible in the case where a door sensor has been installed and connected to the PCN input, and the PcnService has been configured accordingly.

publish.aggregatedData: if true, the service will add the counts from each counter and publish the total on the topic configured in “publishTopic.aggregatedData”.

publishTopic.aggregatedData: this is the name of the topic where the aggregated data will be published. If it is left empty, nothing will be published.

metricName.totalInCount: define the name of the metric that will report the total in counts for the gateway.

metricName.totalOutCount: define the name of the metric that will report the total out counts for the gateway.

metricName.populationCount: define the name of the metric that will report the difference between ins and outs for the gateway. That represents the population inside the vehicle at this moment. Given the counting precision that cannot be 100%, it is possible that this count can be negative, in this case zero will be reported.

gps.enabled: if true, the data published will include the geographical position. In addition, if a topic is configured under “publishTopic.gpsData”, GPS data will be published on that topic at the time interval, independently of the count report. This is intended for vehicle tracking.

publishTopic.gpsData: this is the name of the topic where the geographical data will be published. If it is left empty, nothing will be published.

publish.gps.timeInterval: when > 0, the geographical data will be published on a time basis, the value is in seconds.

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