# ISO11784Tools

    library(ISO11784Tools)

## Introduction

ISO11784 and ISO11785 are standards describing how information should be encoded within passive integrated transponder tags (PIT tags).

ISO11784 describes the binary construction of the information stored in the tag, and ISO11785 describes how it should be read by PIT tag readers.

Despite this, there are some differences in how readers will display the id information depending on user settings and manufacturer choices.

#### Further Reading

- WIKIPEDIA

- RFID NEWS

- ISO ORG

- PRIORITY DESIGN

### ISO11784 In Practice

I encountered 4 different formats of ISO11784 ID codes whilst researching for a PIT tag database. This package is intended to facilitate transformation to and from all of these formats.

It could potentially have other functionality with respect to ISO11784, for example it could connect to ICAR and identify manufacturer of tags along with other metadata.

The 4 formats identified are:

- `Dot Hexadecimal` - e.g. 3E7.1CBE991A14. Manufacturer Code = 3E7 (Note - this is ID is reserved for testing), Animal ID = 1CBE991A14
- `Full Decimal` - e.g. 999123456789012. Manufacturer Code = 999 (Note - this is ID is reserved for testing), Animal ID = 123456789012
- `Full 64 bit Hexadecimal` in two ‘flavours’ that depend on whether the device reverses the transmitted binary ID before converting it to hex or not:
  - `Left Hand Flavour` - e.g. 8000F9DCBE991A14.
  - `Right Hand Flavour` - e.g. 2858997D3B9F0001.

Note, all 4 examples above are the same code.

## Functions

I have created a set of functions to make converting between these formats easy.

### get_iso11784_format

pass a vector of strings containing your tag codes into this function to obtain a vector of the formats

    ISO11784Tools::get_iso11784_format(c('3E7.1CBE991A14','999123456789012','8000F9DCBE991A14','2858997D3B9F0001','blahblah'))
    #> [1] "isodothex"  "isodecimal" "iso64bitl"  "iso64bitr"  "unknown"

### convert_to_X Family

The convert_to_X family of functions takes a vector of strings with your tag codes and converts them into the target format

    ISO11784Tools::convert_to_isodecimal(c('3E7.1CBE991A14','999123456789012','8000F9DCBE991A14','2858997D3B9F0001','blahblah'))
    #> [1] "999123456789012" "999123456789012" "999123456789012" "999123456789012"
    #> [5] NA
    ISO11784Tools::convert_to_isodothex(c('3E7.1CBE991A14','999123456789012','8000F9DCBE991A14','2858997D3B9F0001','blahblah'))
    #> [1] "3E7.1CBE991A14" "3E7.1CBE991A14" "3E7.1CBE991A14" "3E7.1CBE991A14"
    #> [5] NA
    ISO11784Tools::convert_to_iso64bitl(c('3E7.1CBE991A14','999123456789012','8000F9DCBE991A14','2858997D3B9F0001','blahblah'))
    #> [1] "8000F9DCBE991A14" "8000F9DCBE991A14" "8000F9DCBE991A14" "8000F9DCBE991A14"
    #> [5] NA
    ISO11784Tools::convert_to_iso64bitr(c('3E7.1CBE991A14','999123456789012','8000F9DCBE991A14','2858997D3B9F0001','blahblah'))
    #> [1] "2858997D3B9F0001" "2858997D3B9F0001" "2858997D3B9F0001" "2858997D3B9F0001"
    #> [5] NA

### convert_to_all

    ISO11784Tools::convert_to_all(c('3E7.1CBE991A14','999123456789012','8000F9DCBE991A14','2858997D3B9F0001','blahblah'))
    #> # A tibble: 5 × 6
    #>   value            format     isodecimal      isodothex      iso64bitl iso64bitr
    #>   <chr>            <chr>      <chr>           <chr>          <chr>     <chr>
    #> 1 3E7.1CBE991A14   isodothex  999123456789012 3E7.1CBE991A14 8000F9DC… 2858997D…
    #> 2 999123456789012  isodecimal 999123456789012 3E7.1CBE991A14 8000F9DC… 2858997D…
    #> 3 8000F9DCBE991A14 iso64bitl  999123456789012 3E7.1CBE991A14 8000F9DC… 2858997D…
    #> 4 2858997D3B9F0001 iso64bitr  999123456789012 3E7.1CBE991A14 8000F9DC… 2858997D…
    #> 5 blahblah         unknown    <NA>            <NA>           <NA>      <NA>

`convert_to_all` takes a vector of strings and returns a 6 column tibble with detected format and all the possible conversions. It simply wraps the previous 5 functions into one and outputs as a tibble to save some time for the user

### to Family

The `convert_to_X` family of functions are wrappers for lower level functions that convert to and from the `Full Decimal` format. The `Full Decimal` format and the `Dot Hexadecimal` format were the first I encountered, and seem to be the most prevalent. I chose `Full Decimal` as the primary format for this package, and created functions to convert from and to that format in the early stages of development. Hence, these functions center on `Full Decimal`.

Rather than give full examples of these I will simply list them here for reference. Each of these functions will accept a single string or a vector of strings and will return `warning` and `NA` if the format is not as expected, but will still convert anything within a vector that is the correct format.

- From `Full Decimal`:

  - `isodecimal_to_iso64bitleft`
  - `isodecimal_to_iso64bitright`
  - `isodecimal_to_isodothex`

- To `Full Decimal`:

  - `iso64bitleft_to_isodecimal`
  - `iso64bitright_to_isodecimal`
  - `isodothex_to_isodecimal`

### Lowest Level Family

The above functions are built on base converters that are included as imported functions for convenience rather than intended for direct use.

These functions are written to allow conversion between the three bases; binary, decimal, and hexadecimal, to the maximum limit of the R `numeric` data type; `0b1000000000000000000000000000000000000000000000000000000`, `18014398509481984`, and `0x40000000000000` respectively.

`R` has limitations with regard to maximum values held in `integer` and `numeric` data types. I don’t know why this is so I won’t try to expand on the reason here. ISO 11784 ID codes are generally larger than the `integer` maximum, but smaller than the `numeric` maximum. Other packages might have quicker versions of these functions that I haven’t found (happy to receive suggestions!), so I needed to build them from scratch.

- `binary_to_decimal`
- `binary_to_hexadecimal`
- `decimal_to_binary`
- `decimal_to_hexadecimal`
- `hexadecimal_to_binary`
- `hexadecimal_to_decimal`

### The End. Enjoy!