Document operations with the tag

data/main_fields.yaml

@@ -158,6 +158,7 @@
 
 - key: 53
   name: nominal_full_length
+  required: recommended
   category: fff
   type: number
   unit: mm
@@ -168,6 +169,7 @@
 
 - key: 54
   name: actual_full_length
+  required: recommended
   category: fff
   type: number
   unit: mm
@@ -483,4 +485,4 @@
   description:
     - Recommended drying time (at `drying_temperature`).
 
-# First unused key: 59
+# First unused key: 59

docs_src/nfc_data_format.md

@@ -67,6 +67,7 @@
    1. **Auxiliary section** (optional, CBOR map)
       1. Positioned at the beginning of the auxiliary region.
       1. Intended for dynamic information, intended to be updated by the printers.
+      1. SHALL have at least 16 B allocated if present. 32 B is recommended.
 1. Unused space in the sections (outside of the region CBOR) SHALL NOT contain any meaningful working data. It SHOULD be filled with zeroes on tag initialization, but there are no requirements on upkeeping that afterwards. Users CAN update the regions with smaller data, leaving remnants of the original data behind.
 
 ## 3. Specification common to all sections

docs_src/nfc_technical_details.md

@@ -6,27 +6,77 @@
 - [Concise Binary Object Representation (CBOR)](https://cbor.io/)
 
 ## 2. Notes & recommendations
-   1. The standard was designed with ICODE SLIX2 320 B tag in mind, but it is meant be compatible with all NFC-V tags.
-      - Smaller tags might not fit all features/data the OpenPrintTag standard offers. It is up to the manufacturers to decide what data they want to provide in that case.
-   1. We recommend to **expand the payload of the NDEF record so that the whole available memory of the NFC tag is used.**
-
-      - The idea is that the factory can fully lock the blocks containing the NDEF  headers and would only keep the memory pool open. (Possibly write protecting  part of it as well).
-      - Part of the memory pool is auxiliary section, which we want to be able to write to without having to edit other structures/shuffle things around.
-   1. The meta section allows the manufacturers to configure the payload structure so that it fits their purposes and the used NFC tag specifics:
-      1. The auxiliary region can be adjusted or even omitted, based on the NFC tag available memory.
-         - It is not specified that the auxiliary region must be after the main region. Auxiliary region can possibly be located **before** the main region, if the meta section says so. We however recommend **putting the main region before the auxiliary region**, so that it can be protected together with the NDEF header.
-   1. **AFI**: We recommend setting the AFI register to 0 and locking/password protecting it.
-   1. **DSFID**: The DSFID register is reserved for future use. It shall be set to 0 and locked/password protected.
-   1. **EAS**: Implementing EAS is up to each manufacturer discretion. We again recommend locking/password protecting it.
-   1. The specification was written in such way so that it wouldn't need explicit versioning.
-      - New keys can easily be introduced without breaking backwards compatibility.
-      - Deprecated keys will never be reused.
-      - If there would be substantial changes to the standard that would break backwards compatibility, a new MIME type will be used for the new format.
-
-## 3. Write protection
+1. The standard was designed with ICODE SLIX2 320 B tag in mind, but it is meant be compatible with all NFC-V tags.
+   - Smaller tags might not fit all features/data the OpenPrintTag standard offers. It is up to the manufacturers to decide what data they want to provide in that case.
+1. We recommend to **expand the payload of the NDEF record so that the whole available memory of the NFC tag is used.**
+   - The idea is that the factory can fully lock the blocks containing the NDEF headers and would only keep the memory pool open. (Possibly write protecting  part of it as well).
+   - Part of the memory pool is auxiliary section, which we want to be able to write to without having to edit other structures/shuffle things around.
+1. The meta section allows the manufacturers to configure the payload structure so that it fits their purposes and the used NFC tag specifics:
+   1. The auxiliary region can be adjusted or even omitted, based on the NFC tag available memory.
+      - It is not specified that the auxiliary region must be after the main region. Auxiliary region can possibly be located **before** the main region, if the meta section says so. We however recommend **putting the main region before the auxiliary region**, so that it can be protected together with the NDEF header.
+1. The specification was written in such way so that it wouldn't need explicit versioning.
+   - New keys can easily be introduced without breaking backwards compatibility.
+   - Deprecated keys will never be reused.
+   - If there would be substantial changes to the standard that would break backwards compatibility, a new MIME type will be used for the new format.
+
+## 3. Tag operations
+The OpenPrintTag standard defines these types of operations with the tag:
+
+### 3.1 Read operation
+Read operation does not change any data on the tag and is not subject to any limitations.
+
+1. Regions MAY be padded with invalid/leftover data after the section CBOR object. Readers SHALL ignore this data.
+1. Example of a typical read operation (results of the steps can be cached to speed up subsequent operations):
+   1. Locate the NDEF TLV record.
+   1. Locate the OPT NDEF record within the NDEF TLV.
+   1. Read the meta section (one CBOR object immediately at the beginning of the NDEF record).
+   1. Determine positions of the main and optional auxiliary regions from the meta section data.
+   1. Read through the required region and pick out the required fields.
+
+### 3.2 Update operation
+Update operation updates selected fields in the auxiliary (or main) region.
+
+1. The operation SHOULD NOT write to any blocks outside the updated region.
+   1. *Note: Writes to the tag outside of the auxiliary region MAY be password-protected or completely locked (see the Write protection section). Auxiliary region data update can fail if the operation attempts to rewrite the entire tag.*
+1. The operation SHALL NOT change any data outside of the updated region.
+   1. The operation SHALL NOT change the position of the OpenPrintTag NDEF record within the tag.
+   1. The operation SHALL NOT change positions or sizes of the regions.
+   1. The operation SHALL NOT change any data in the metadata section.
+1. The operation SHALL NOT change data of any unrelated fields.
+   1. Fields with unknown keys or invalid data SHALL be preserved.
+   1. Modifications that do not change the CBOR canonical representation (for example reordering map items) are permitted, but not recommended.
+1. The operation MAY intentionally remove fields.
+1. If the size of the section (CBOR object) within the region shrinks, the leftover data CAN be left as-is. Readers SHALL ignore any padding data past the section CBOR object.
+1. Example of a typical update operation (changing one field value):
+   1. Parse the TLV record, NDEF record and metadata section in the same way as in the read operation.
+   1. Read the updated region to the memory.
+   1. Generate new data for the region with the updated field.
+   1. Determine the smallest memory region that differs between the old and new data.
+   1. Only write the differing region to the tag.
+
+### 3.3 (Re)initialization operation
+Initialization rewrites the whole tag and is only intended to be done once.
+
+Initializing a tag requires knowledge about the specific tag model and general managerial decisions:
+   1. Unlocking the tag if it has been locked.
+   1. Determining the allocation size of the OPT NDEF record.
+   1. Determining the auxiliary region size and position.
+      1. Auxiliary region SHALL be aligned to the tag memory block boundaries (typically 4B). Main region is generally not intended to be updated, so its alignment is not required.
+   1. Configuring relevant NFC tag register:
+      1. **AFI**: We recommend setting the AFI register to 0 and locking/password protecting it.
+      1. **DSFID**: The DSFID register is reserved for future use. It shall be set to 0 and locked/password protected.
+      1. **EAS**: Implementing EAS is up to each manufacturer discretion. We again recommend locking/password protecting it.
+   1. Configuring the write protection of the tag (see the Write protection section below).
+
+### 3.4 Reusing the tag
+Reusing the tag for a completely different material is generally considered an update operation, as it only clears both main and auxiliary regions and fills the main region with new data.
+
+The tag can however possibly contain additional NDEF records, for example URI with a link relevant to the original material. In that case, removing the NDEF URI record would be desirable, which would constitute a reinitialization operation.
+
+## 4. Write protection
 The OpenPrintTag standard offers the following options also considers ways to prevent the tags from being overwritten by malicious actors.
 
-### 3.1 Protecting the auxiliary region
+### 4.1 Protecting the auxiliary region
 Auxiliary region cannot be reasonably write-protected, because it is intended to be written to by the printers and that needs to be plug-an-play for user comfort.
 Therefore it can contain invalid data when a customer first brings it from the shop (because anyone could have written anything to it).
 
@@ -35,18 +85,18 @@ When a tag is detected by the device and the workgroup doesn't match, the device
 
 As a result, the user should be alerted to wipe the auxiliary region on first usage of the filament and then, because the workgroup is the same, there should be no further obstructions.
 
-### 3.2 Protecting the rest of the tag
+### 4.2 Protecting the rest of the tag
 The rest of the tag (NDEF header, meta region, main region) can be protected more strongly, because it is not expected to be changed regularily (just for refills or reusing the tag). The form of protection is indicated by the `write_protection` field in the main section.
 
 * The locking mechanisms work on the block level, so we recommend **aligning the regions with the NFC tag blocks**.
 
-#### 3.2.1 `write_protection` items
+#### 4.2.1 `write_protection` items
 {{ enum_table("write_protection_enum") }}
 
-#### 3.2.2 `irreversible` protection
+#### 4.2.2 `irreversible` protection
 The irreversible locking can be achiaved using the `LOCK BLOCK` command on the whole tag (except the auxiliary region). We do not recommend this, as it prevents reuse of the NFC tag.
 
-#### 3.2.3 `protect_page_unlockable` protection (SLIX2-specific)
+#### 4.2.3 `protect_page_unlockable` protection (SLIX2-specific)
 Using `protect_page_unlockable` is the recommended way of protecting the tag. It is based on the `PROTECT PAGE` command, which is a SLIX2-specific command.
 
 1. The tag is write-protected using the `PROTECT PAGE` page command.

tests/encode_decode/01_info.yaml

@@ -60,7 +60,9 @@ raw_data:
   aux: a000000000000000000000000000000000000000000000000000000000000000000000
 uri: https://3dtag.org/s/334c54f088
 validate:
-  warnings: []
+  warnings:
+  - Missing recommended field 'nominal_full_length'
+  - Missing recommended field 'actual_full_length'
   errors: []
 opt_check:
   warnings: []

tests/encode_decode/02_info.yaml

@@ -56,7 +56,9 @@ raw_data:
   aux: a000000000000000000000000000000000000000000000000000000000000000000000
 uri: https://3dtag.org/s/7ab2acb509
 validate:
-  warnings: []
+  warnings:
+  - Missing recommended field 'nominal_full_length'
+  - Missing recommended field 'actual_full_length'
   errors: []
 opt_check:
   warnings: []

tests/encode_decode/04_info.yaml

@@ -61,6 +61,7 @@ uri: https://www.3dxtech.com/
 validate:
   warnings:
   - Missing recommended field 'gtin'
+  - Missing recommended field 'nominal_full_length'
   - Missing recommended field 'preheat_temperature'
   errors: []
 opt_check:

tests/encode_decode/05_info.yaml

@@ -48,6 +48,8 @@ validate:
   - Missing recommended field 'manufactured_date'
   - Missing recommended field 'nominal_netto_full_weight'
   - Missing recommended field 'actual_netto_full_weight'
+  - Missing recommended field 'nominal_full_length'
+  - Missing recommended field 'actual_full_length'
   - Missing recommended field 'empty_container_weight'
   - Missing recommended field 'primary_color'
   - Missing recommended field 'density'