.. _volume-keys:

Encode Volume Keys
==================

Introduction
------------
This section will describe how to activate Volume License Keys and monitor
remaining volume.

.. _volume-key-activation:

Activating Volume License Keys
------------------------------
Activating Volume License Keys is done via the ItemEncode API. End users will be 
provided a string of ASCII characters, which will need to be sent to the 
ItemEncode device. Adding the license key should be done while the ItemEncode
device is in the :ref:`Configuration State<configuration-state>`. It will take 
several seconds to complete.


.. code-block:: csharp

    Device device;
    LicenseKey licenseKey;

    licenseKey.LicenseKeyPayload = <data>;

    device.AddLicenseKey(licenseKey);

.. _configuring-dor:

Configuring the Device of Record
--------------------------------
In a :ref:`Pipeline System<pipeline-encoding>`, upstream encoders must be made 
aware of the Device of Record. This is done to so that only one ItemEncode 
device has to keep track of the encoding volume count. Any device operating in 
either :ref:`Encode<encode-mode>` or 
:ref:`Verify Tag Chip Data<verify-tag-chip-data-mode>` mode will need either 
a Volume License or a Device of Record configured. The Device of Record is 
configured as part of the 
:ref:`OperationResponsibility<operation-responsibility>` object in the
:ref:`DeviceConfig<device-config>`.

.. code-block:: csharp
    
    DeviceConfig deviceConfig;
    OperationResponsibility operationResponsibility;
    
    STPDevice verifier("SpeedwayR-ZZ-ZZ-ZZ");
    
    // Add the Device of Record. This tells the ItemEncode device where the 
    // encoding volume is maintained. If there is no Device of Record set,
    // the device will assume that it is the Device of Record.
    operationResponsibility.device_of_record(verifier);

    deviceConfig.operation_responsibility = operationResponsibility;

.. _volume-key-monitoring:

Monitoring Remaining Volume
---------------------------
There are two ways in which to monitor the remaining volume. The application can
query the :ref:`OperationData<operation-data>` to get the remaining number of 
encodes and/or they can receive an asynchronous 
:ref:`LowEncodeVolumeEvent<low-encode-volume-event>`.

Querying OperationData
++++++++++++++++++++++
The :ref:`OperationData<operation-data>` contains several useful pieces of 
information about the current status of the ItemEncode device. One of those 
pieces is the :ref:`OperationMetrics<operation-metrics>` object. This object 
contains the remaining number of encodes for both Monza and non-Monza tags. 
This object can be queried while the device is in any state. 

Handling
^^^^^^^^
.. code-block:: csharp
    
    Device device;

    OperationData operationData = device.GetOperationData();

Output
^^^^^^
.. code-block:: python
    :emphasize-lines: 11,12
   
    operation_data
    {
        operation_details 
        {
            serial_number: "370-13-27-0066"
            firmware_version: "2.2.12.240"
            region: "Latin America 902-928 MHz"
            installed_features: "ItemEncodeMonza"
            operation_metrics 
            {
                remaining_monza_encodes: 279
                remaining_non_monza_encodes: 0
                tag_metrics 
                {
                    tag_chip: [e2801130]
                    encode_metrics 
                    {
                        total_count: 2721
                        pass_count: 2721
                        fail_count: 0
                        void_count: 0
                    }
                }
                inter_device_communication_metrics 
                {
                    serial_number: "12345678900"
                    received_message_count: 2730
                }
            }
            monza_volume_key_id: 190412343
        }
    }

Receiving LowEncodeVolumeEvent
++++++++++++++++++++++++++++++
ItemEncode devices can also generate a 
:ref:`LowEncodeVolumeEvent<low-encode-volume-event>` to notify the application
that it is running low on encode volume. This is a type of 
:ref:`DeviceEventReport<device-event-report>`. The event is configurable as part
of the :ref:`DeviceEventConfig<device-event-config>`. Independent encode volume
thresholds can be set for both Monza and non-Monza tags. ItemEncode can also be
configured to repeat the event according to a specified period. Both the 
threshold and period are configured in terms of number of encode attempts.

Configuration
^^^^^^^^^^^^^

.. code-block:: csharp

    Device device;
    DeviceConfig deviceConfig;
    DeviceEventConfig deviceEventConfig; 
    LowEncodeVolumeEventConfig lowEncodeVolumeEventConfig;

    lowEncodeVolumeEventConfig.enable_low_encode_volume_events = true;

    // Configure the LowEncodeVolumeEvent to trigger when it gets below 400k 
    // encode attempts remaining.
    lowEncodeVolumeEventConfig.MonzaThreshold         = 400000;
    lowEncodeVolumeEventConfig.NonMonzaThreshold      = 400000;

    // Configure the LowEncodeVolumeEvent to send another event every 50000 
    // encode attempts.
    lowEncodeVolumeEventConfig.MonzaReminderPeriod    = 50000;
    lowEncodeVolumeEventConfig.NonMonzaReminderPeriod = 50000;

    deviceEventConfig.low_encode_volume_event_config = lowEncodeVolumeEventConfig;
    deviceConfig.report_config.device_event_config = deviceEventConfig;

    device.SetDeviceConfig(deviceConfig);

Handling
^^^^^^^^

.. code-block:: csharp
    
    void OnDeviceEventReport(DeviceEventReport report)
    {
        if (report.low_encode_volume_event != null)
        {
            // Handle Event
            report.low_encode_volume_event.Print();
        }
    }

Output
^^^^^^

.. code-block:: python

    device_event_report
    {
        low_encode_volume_event
        {
            low_encode_volume_event_type: LOW_ENCODE_VOLUME_EVENT_MONZA
            remaining_monza_encodes: 400000
            remaining_non_monza_encodes: 0
        }
    }
