.. _license-model:

License Model
=============

Introduction
------------
The ItemEncode licensing model is a consumption-based model that tracks volume 
of tag encoding operations executed by the ItemEncode system. Users purchase a 
Volume License Key for a set volume/number of encoding operations and apply 
this key to their ItemEncode devices. The key unlocks the ItemEncode system to 
encode Monza or non-Monza tags. The Volume License Key is a one time use key 
that is sent to the ItemEncode device to increase the count of remaining encode
volume.

In addition to the Volume License Key, all ItemEncode devices must have the 
appropriate Speedway Feature Key installed.

.. _speedway-feature-keys:

Speedway Feature Keys
---------------------
ItemEncode uses Speedway Feature Keys to enable basic device operation depending
on what is required for the system. To acquire a Speedway Feature Key, please 
contact Impinj Support with the serial numbers of the devices requiring the key.

* **ItemEncodeMonza** \- This Feature Key enables the ability to encode 
  :ref:`supported Impinj Monza tags<tag-chips>`. It must be installed on all 
  ItemEncode devices in the system.

* **ItemEncodeNonMonza** \- This Feature Key enables the ability to encode 
  :ref:`supported non-Monza tags<tag-chips>`. It must be installed on all 
  ItemEncode devices in the system.

.. note:: The installation of Speedway Feature Keys is documented in the `RShell Reference Manual <https://support.impinj.com/hc/en-us/articles/202755298-Reader-Documentation>`_

Volume License Keys
-------------------
The ItemEncode Volume License Key is a one time use key that increases the 
volume of tags ItemEncode can attempt to encode. End users can purchase these 
keys from Impinj. Separate keys are available for Monza and non-Monza tag 
encodes. When the key is applied to the ItemEncode system, it will add to the 
existing volume of encodes. When ItemEncode attempts to encode a tag, it will 
decrement an encode from the volume of encodes available in the ItemEncode 
system. When the volume of encodes available on the system reaches zero, the 
ItemEncode device will no longer be able to encode tags.

Volume Management in a Pipeline System
++++++++++++++++++++++++++++++++++++++
In an :ref:`ItemEncode Pipeline System<pipeline-encoding>`, the same tag could 
be encoded by multiple devices. To keep the ItemEncode devices in sync with each
other, the remaining volume is tracked on only one device. This device is 
referred to as the Device of Record. It can be either an encoder or verifier. 
The other encoders in the :ref:`Pipeline System<pipeline-encoding>` will need to
be configured to communicate with the Device of Record. For more information on 
how to configure the Device of Record in a 
:ref:`Pipeline System<pipeline-encoding>`, please see 
:ref:`Configuring the Device Of Record<configuring-dor>`.

.. note:: While only the Device of Record requires a Volume License Key in a Pipeline System, all devices in the system will still require the Speedway Feature Keys.

.. image:: _static/PipelineDoR.png
    :align: center

Volume License Key Activation
+++++++++++++++++++++++++++++
Unlike the Speedway Feature Keys, the Volume License Keys are activated using 
the ItemEncode API. For more information on how to activate Volume License Keys,
please see :ref:`Activating Volume License Keys<volume-key-activation>` in the 
API Guide.

Volume Monitoring
+++++++++++++++++
There are two ways in which to monitor the remaining volume. At any point, the
ItemEncode device may be queried for the :ref:`OperationData<operation-data>`. 
This object will contain the remaining volume of encodes for both Monza and 
non-Monza tags. In addition, the ItemEncode device can generate a 
:ref:`LowEncodeVolumeEvent<low-encode-volume-event>` when the remaining volume
passes below a certain threshold. For more information on monitoring remaining
volume, please see :ref:`Monitoring Remaining Volume<volume-key-monitoring>` in 
the API Guide.

Volume Decrementing Exceptions
++++++++++++++++++++++++++++++
There are some exceptions to decrementing the remaining Monza or non-Monza 
encoding volume. In scenarios where ItemEncode can determine that no encoding is
taking place, the volume will not be decremented. The following 
:ref:`TagOperationResult<tag-operation-result>` values correspond to these 
exceptions:

- TAG_OPERATION_RESULT_PASS_ALREADY_DONE
- TAG_OPERATION_RESULT_RETRY
- TAG_OPERATION_RESULT_RETRY_INSUFFICIENT_POWER
- TAG_OPERATION_RESULT_RETRY_NO_RESPONSE_FROM_TAG
- TAG_OPERATION_RESULT_RETRY_SERIALIZATION_JOB_QUEUE_EMPTY
- TAG_OPERATION_RESULT_RETRY_TID_TABLE_NO_MATCH
- TAG_OPERATION_RESULT_RETRY_ORDERED_LIST_EMPTY
- TAG_OPERATION_RESULT_FAIL_SERIALIZATION_JOB_QUEUE_EMPTY
- TAG_OPERATION_RESULT_FAIL_TID_TABLE_NO_MATCH
- TAG_OPERATION_RESULT_FAIL_ORDERED_LIST_EMPTY
- TAG_OPERATION_RESULT_FAIL_TAG_CHIP_NOT_SUPPORTED
- TAG_OPERATION_RESULT_FAIL_TAG_CHIP_SUPPORTED_LICENSE_KEY_NOT_INSTALLED
- TAG_OPERATION_RESULT_FAIL_TAG_NOT_INVENTORIED
- TAG_OPERATION_RESULT_FAIL_VOLUME_EXHAUSTED
- TAG_OPERATION_RESULT_FAIL_SERIAL_NUMBER_RANGE_EMPTY
- TAG_OPERATION_RESULT_FAIL_VOYANTIC_TEST_RESULT_MISSING
- TAG_OPERATION_RESULT_FAIL_VOYANTIC_TEST_RESULT_FAILED
- TAG_OPERATION_RESULT_FAIL_TID_TABLE_INVALID_CONFIG
- TAG_OPERATION_RESULT_FAIL_FILTER_NO_MATCH
- TAG_OPERATION_RESULT_FAIL_VOLUME_LICENSE_REVOKED
