2018-05-30 10:49:40 +00:00
|
|
|
|
Tags
|
2018-06-16 10:41:12 +00:00
|
|
|
|
####
|
2018-05-30 10:49:40 +00:00
|
|
|
|
Devicehub can generate tags, which are synthetic identifiers that
|
|
|
|
|
identify a device in an organization. A tag has minimally two fields:
|
|
|
|
|
the ID and the Registration Number of the organization that generated
|
|
|
|
|
such ID.
|
|
|
|
|
|
|
|
|
|
In Devicehub tags are created empty, this is without any device
|
|
|
|
|
associated, and they are associated or **linked** when they are assigned
|
|
|
|
|
to a device. In Devicehub you usually use the AndroidApp to link
|
|
|
|
|
tags and devices.
|
|
|
|
|
|
|
|
|
|
The organization that created the tag in the Devicehub (which can be
|
|
|
|
|
impersonating the organization that generated the ID) is called the
|
|
|
|
|
**tag provider**. This is usual when dealing with other organizations
|
|
|
|
|
devices.
|
|
|
|
|
|
|
|
|
|
A device can have many tags but a tag can only be linked to one device.
|
|
|
|
|
As for the actual implementation, you cannot unlink them.
|
|
|
|
|
|
|
|
|
|
Devicehub users can design, generate and print tags, manually setting
|
2018-09-20 07:28:52 +00:00
|
|
|
|
an ID and a tag provider. Note though that these virtual tags don't have
|
|
|
|
|
to forcefully be printed or have a physical representation
|
|
|
|
|
(this is not imposed at system level).
|
2018-05-30 10:49:40 +00:00
|
|
|
|
|
2018-09-30 17:40:28 +00:00
|
|
|
|
Tags are case insensitive and are converted to lower-case in
|
|
|
|
|
Devicehub.
|
|
|
|
|
|
2018-06-19 20:49:42 +00:00
|
|
|
|
eTags
|
|
|
|
|
*****
|
2018-05-30 10:49:40 +00:00
|
|
|
|
We recognize a special type of tag, the **eReuse.org tags (eTag)**.
|
|
|
|
|
These are tags defined by eReuse.org and that can be issued only
|
|
|
|
|
by tag providers that comply with the eReuse.org requisites.
|
|
|
|
|
|
|
|
|
|
The eTags are designed to empower device exchange between
|
|
|
|
|
organizations and identification efficiency. They are built with durable
|
2018-09-20 07:28:52 +00:00
|
|
|
|
plastic and have a QR code, a NFC chip and a written ID.
|
2018-05-30 10:49:40 +00:00
|
|
|
|
|
|
|
|
|
These tags live in separate databases from Devicehubs, empowered by
|
2018-09-20 07:28:52 +00:00
|
|
|
|
the `eReuse.org Tag <https://github.com/ereuse/tag>`_ software.
|
|
|
|
|
By using this software, eReuse.org certified tag providers
|
|
|
|
|
can create and manage the tags, and send them to Devicehubs of their
|
|
|
|
|
choice.
|
|
|
|
|
|
|
|
|
|
The section *Use-case with eTags* shows the use-case of these
|
|
|
|
|
eTags.
|
2018-05-30 10:49:40 +00:00
|
|
|
|
|
|
|
|
|
Tag ID design
|
2018-06-16 10:41:12 +00:00
|
|
|
|
=============
|
2018-05-30 10:49:40 +00:00
|
|
|
|
The eTag has a fixed schema for its ID: ``XXX-YYYYYYYYYYYYYY``, where:
|
|
|
|
|
|
|
|
|
|
- *XX* is the **eReuse.org Tag Provider ID (eTagPId)**.
|
|
|
|
|
- *YYYYYYYYYYYY* is the ID of the tag in the provider..
|
|
|
|
|
|
|
|
|
|
The eTagPid identifies an official eReuse.org Tag provider; this ID
|
|
|
|
|
is managed by eReuse.org in a public repository. eTagPIds are made of
|
|
|
|
|
2 capital letters and numbers.
|
|
|
|
|
|
|
|
|
|
The ID of the tag in the provider (*YYYYYYYYYYYYYY*) consists from
|
|
|
|
|
5 to 10 capital letters and numbers (registering a maximum of 10^12
|
|
|
|
|
tags).
|
|
|
|
|
|
|
|
|
|
As an example, ``FO-A4CZ2`` is a tag from the ``FO`` tag provider
|
|
|
|
|
and ID ``A4CZ2``.
|
|
|
|
|
|
|
|
|
|
Creating tags
|
2018-06-16 10:41:12 +00:00
|
|
|
|
*************
|
2018-05-30 10:49:40 +00:00
|
|
|
|
You need to create a tag before linking it to a device. There are
|
|
|
|
|
two ways of creating a tag:
|
|
|
|
|
|
|
|
|
|
- By performing ``POST /tags?ids=...`` and passing a list of tag IDs
|
|
|
|
|
to create. All users can create tags this method, however they
|
|
|
|
|
cannot create eTags. Get more info at the endpoint docs.
|
|
|
|
|
- By executing in a terminal ``flask create-tags <ids>`` and passing
|
|
|
|
|
a list of IDs to create. Only an admin is supposed to use this method,
|
|
|
|
|
which allows them to create eTags. Get more info with
|
|
|
|
|
``flask create-tags --help``.
|
|
|
|
|
|
|
|
|
|
Note that tags cannot have a slash ``/``.
|
|
|
|
|
|
|
|
|
|
Linking a tag
|
2018-06-16 10:41:12 +00:00
|
|
|
|
*************
|
2018-05-30 10:49:40 +00:00
|
|
|
|
Linking a tag is joining the tag with the device.
|
|
|
|
|
|
|
|
|
|
In Devicehub this process is done when performing a Snapshot (POST
|
|
|
|
|
Snapshot), by setting tag ids in ``snapshot['device']['tags']``. Future
|
|
|
|
|
implementation will allow setting to the organization to ensure
|
|
|
|
|
tags are inequivocally correct.
|
|
|
|
|
|
|
|
|
|
Note that tags must exist in the database prior this.
|
|
|
|
|
|
|
|
|
|
You can only link once, and consecutive Snapshots that have the same
|
|
|
|
|
tag will validate that the link is correct –so it is good praxis to
|
|
|
|
|
try to always provide the tag when performing a Snapshot. Tags help
|
|
|
|
|
too in finding devices when these don't generate a ``HID``. Find more
|
|
|
|
|
in the ``Snapshot`` docs.
|
|
|
|
|
|
|
|
|
|
Getting a device through its tag
|
2018-06-16 10:41:12 +00:00
|
|
|
|
********************************
|
2018-05-30 10:49:40 +00:00
|
|
|
|
When performing ``GET /tags/<tag-id>/device`` you will get directly the
|
|
|
|
|
device of such tag, as long as there are not two tags with the same
|
|
|
|
|
tag-id. In such case you should use ``GET /tags/<ngo>/<tag-id>/device``
|
2018-09-20 07:28:52 +00:00
|
|
|
|
to unequivocally get the correct device (feature to develop).
|
2018-05-30 10:49:40 +00:00
|
|
|
|
|
|
|
|
|
Tags and migrations
|
2018-06-16 10:41:12 +00:00
|
|
|
|
*******************
|
2018-05-30 10:49:40 +00:00
|
|
|
|
Tags travel with the devices they are linked when migrating them. Future
|
|
|
|
|
implementations can parameterize this.
|
|
|
|
|
|
2018-11-17 16:03:03 +00:00
|
|
|
|
Photochromic tags
|
|
|
|
|
*****************
|
|
|
|
|
The photochromic Reversible Tag helps the end-user to identify a
|
|
|
|
|
legitimate device that has correctly refurbished by an eReuse.org
|
|
|
|
|
authorized refurbisher, without the hassle to read the QR code.
|
|
|
|
|
|
|
|
|
|
Only eReuse.org authorized organizations can use the Photochromic tags.
|
|
|
|
|
|
2018-09-18 16:45:29 +00:00
|
|
|
|
Use-case with eTags
|
|
|
|
|
*******************
|
|
|
|
|
We explain the use-case of tagging a device with an :ref:`tags:eTags`,
|
|
|
|
|
going through the manufacturing of the tags, their distribution and
|
|
|
|
|
the final linkage between tag and computer.
|
|
|
|
|
|
|
|
|
|
For this use-case we suppose we want 100 eTags.
|
|
|
|
|
|
|
|
|
|
Actors
|
|
|
|
|
======
|
|
|
|
|
|
|
|
|
|
- Tag provider: organization that orders and manages the eTags; it is
|
|
|
|
|
certified by eReuse.org thus having permission to order the tags.
|
|
|
|
|
- NFC Tag manufacturer.
|
|
|
|
|
- Photochromic tag manufacturer.
|
|
|
|
|
- User: organization that uses the tags.
|
|
|
|
|
|
|
|
|
|
Requirements
|
|
|
|
|
============
|
|
|
|
|
|
|
|
|
|
- At least one eReuse.org Devicehub. One Devicehub can contain several
|
|
|
|
|
organizations and inventories, or organizations can have their own
|
|
|
|
|
copy of Devicehub. Devicehub work distributely over the Internet.
|
|
|
|
|
- One `eReuse.org Tag <https://github.com/ereuse/tag>`_ running in a
|
|
|
|
|
server over the Internet by the *tag provider*.
|
|
|
|
|
|
|
|
|
|
Use case
|
|
|
|
|
========
|
|
|
|
|
|
|
|
|
|
1. The *tag provider* enters into the server containing the
|
|
|
|
|
*eReuse.org Tag* software and executes the command
|
|
|
|
|
``etag create-tags 100 --csv file.csv``, which creates 100
|
|
|
|
|
tags in the database and saves their URLs into a spreadsheet CSV file
|
|
|
|
|
called *file.csv*.
|
|
|
|
|
2. The *tag provider* sends the CSV file to the *NFC tag manufacturer*
|
|
|
|
|
and orders the 100 tags.
|
|
|
|
|
3. The *NFC tag manufacturer* creates those tags (NFC plus QR code)
|
|
|
|
|
and updates the CSV file with the NFC ID of each tag, so each row
|
|
|
|
|
of the CSV file contains the URL sent by the *tag provider* and
|
|
|
|
|
the ID of the NFC tag created by the *NFC tag manufacturer*.
|
|
|
|
|
4. The *Tag provider* updates *eReuse.org Tag* with the ID of the
|
|
|
|
|
NFC by executing ``etag update-tags file.csv`` where *file.csv* is the
|
|
|
|
|
file sent by the *NFC tag manufacturer*.
|
|
|
|
|
5. The *Tag provider* orders 100 photochromic tags to the *Photochromic
|
|
|
|
|
tag manufacturer*. Note that these tags don't require any special
|
|
|
|
|
treatment.
|
|
|
|
|
6. The *Photochromic tag manufacturer* sends back 100 tags.
|
|
|
|
|
7. The *Tag provider* distributes the eTags (NFC and photochromic) to
|
|
|
|
|
several organizations, *users*, both physically by sending them and
|
|
|
|
|
virtually by executing ``etag set-tags http://some-devicehub.com
|
|
|
|
|
0 100``; this marks the tags in *eReuse.org Tag*
|
|
|
|
|
as *sent to some-devicehub.com* and creates the tags in that
|
|
|
|
|
Devicehub.
|
|
|
|
|
8. The *user* receives the tags, sticks them in their devices, and scans
|
|
|
|
|
the NFC or QR codes:
|
|
|
|
|
|
|
|
|
|
1. By using the `eReuse.org Android App <https://github.com/eReuse/eReuseAndroidApp>`_
|
|
|
|
|
the user can scan the QR code or the NFC of the eTag.
|
2018-12-03 19:20:25 +00:00
|
|
|
|
2. If the *user* is processing devices with the
|
|
|
|
|
`eReuse.org Workbench <https://github.com/ereuse/workbench>`_, Workbench
|
2018-09-18 16:45:29 +00:00
|
|
|
|
automatically attaches hardware information like serial numbers,
|
|
|
|
|
otherwise the *user* can add that information through the app.
|
|
|
|
|
3. These softwares communicate with the Devicehub of the user and
|
|
|
|
|
command the Devicehub to link the device with the tag.
|
|
|
|
|
4. The Devicehub of the user links the tag.
|
|
|
|
|
5. The Devicehub creates or updates a virtual entity in Everythng
|
|
|
|
|
containing the device and the tag.
|
|
|
|
|
6. If Devicehub or Everythng detect that the tag was linked they won't
|
|
|
|
|
allow this operation. Devicehub can only detect if the app is linked
|
|
|
|
|
by looking at its internal database. Everythng, as it contains all
|
|
|
|
|
device and tag information, validates that the tag is not linked
|
|
|
|
|
elsewhere.
|