Update processes

docs/processes.rst

@@ -19,12 +19,140 @@ Please refer to :ref:`tags:Use case`.
 
 Processing a device with Workbench
 ==================================
+Processing a device with the `eReuse.org Workbench
+<https://github.com/ereuse/workbench>`_ means creating a hardware
+report of the device (including serial numbers and other metadata),
+linking the device with tags, and registering it to a Devicehub.
+
+This is the first step when dealing with a new device with
+the eReuse.org tools, as it registers the device with the database,
+or updates its information if the device existed before. So any
+other process, unless stated contrary, requires this one to be
+performed to a device before.
+
+For generic devices, the process is as follows:
+
+1. The user opens the eReuse.org Android App (App) and selects
+   *add snapshot*.
+2. The user sticks and scans the tags of the device, including the
+   :ref:`tags:eTags`, manufacturer tags (like serial numbers), and
+   tags provided by third-parties like donors.
+3. The user manually introduces other information, like ratings,
+   and submits the information to Devicehub.
+
+For a computer, `This video <https://vimeo.com/250253019>`_ explains
+the process using generic tags, and it is as follows:
+
+1. The user connects the computers to process to an eReuse.org Box
+   running the Workbench Server software using a local network.
+2. Computers boot and automatically execute the eReuse.org Workbench
+   software, generating information from the computer and its components,
+   erasing the data storage components, testing the machine, etc.
+3. During the process, the user opens the Android App and selects
+   the *Workbench* option, which connects the App to a running
+   Workbench Server in the local network.
+4. From now on, like in step 2. from the generic device, the user
+   sticks and scans the tags from the device, specifically the
+   :ref:`tags:eTags` and the ones provided by third-parties. The
+   manufacturer tags are not required as such information is taken
+   by the Workbench automatically.
+5. Android App and Workbench embed the information into a report
+   that is submitted to Devicehub.
+
+Preparing a device for use
+==========================
+Users, like refurbishers, ready the devices so they are suitable
+for trading. This process implies repairing, cleaning...
+
+1. The user scans the tag of the device with the Android App or searches it from the
+   website and selects *actions* > *:ref:`actions:ToPrepare, Prepare <ToPrepare>`*,
+   which informs Devicehub that a device has to be prepared for trading.
+2. The user prepares the device. Upon success, it performs the action
+   :ref:`actions:ToPrepare, Prepare <Prepare>` in the similar way that
+   did in 1.
+3. A prepared device might still not be ready for trading. For example,
+   a seller still might want to clean a device once a trade has been
+   confirmed, as the device would have gathered dust between the
+   preparation and the trading. To denote a final "this device is
+   ready to be shipped to a customer state", the user performs
+   the action :ref:`actions:ReadyToUse` in the same way it did in 1.
+
+If the device is broken or breaks, the user performs the action
+:ref:`actions:ToRepair` denoting that the device has to be repaired,
+and :ref:`actions:Repair` upon success.
+
+Broken devices that are not going to be fixed might be set for
+:ref:`Dispose a device <disposition>`.
 
 Track a device
 ==============
+:ref:`processing a device with workbench` registers into Devicehub
+the required metadata from a device to identify it: a digital
+passport for the device (information submitted in a Devicehub),
+plus a physical passport (a tag that links the device with the digital
+passport). If the physical passport is an :ref:`tags:eTag` then
+it is unforgeable.
+
+The rest of the traceability is based in keeping track of the events
+occurring on the device, for example when it changes location or
+it is traded. eReuse.org allows recording these actions, providing
+mechanisms to ease them or ensure them. Please refer to the specific
+use cases for more information.
+
+Checking device authenticity
+============================
+Any user can check the authenticity of a device registered in a
+Devicehub, even if the user is external, like a customer.
+
+If the device has an :ref:`tags:eTag` or a regular tag generated by
+a Devicehub (stuck on the :ref:`Processing a device with Workbench`),
+the process is as follows:
+
+1. The user scans the QR code with a smartphone using a generic QR
+   codes scanner.
+2. The scanner opens the browser and takes the user to a webpage
+   containing public information of the device. Part of this
+   information are the serial numbers and other IDs of the device,
+   and a set of instructions in how to challenge the Photochromic
+   tag of the device, if the device has one stuck, to double-check
+   its veracity.
+3. The user tests the photochromic tag by touching the flash bulb of
+   the smartphone with the tag for, at least, 6 seconds, checking
+   that the tag changes color temporarily.
+
+Other ways of checking device authenticity are:
+
+- Scanning the QR code stuck and comparing the serial numbers of the
+  device with the ones of the public webpage.
+- Directly applying the photochromic challenge.
+
+Workbench and Devicehub detect changes in computer components. Certain
+scenarios where the computer passed by untrusted users require
+ensuring that no component has been taken.
+A deeper verification process is re-processing the computer with
+Workbench, generating a new report that updates the information of
+the computer in the Devicehub, ultimately showing the differences
+in removed and added components.
+
+Finally, the eReuse.org team is developing, using the platform Evrythng,
+a global record of devices, which takes non-private IDs of the devices
+of participating Devicehubs and records the most important life
+events of the devices. This database is publicly available, so
+users can search on it an ID of a device, for example the S/N or the one
+written in a tag, like an :ref:`tags:eTag`, and know which Devicehub
+registered in, ultimately accessing the public information of the device.
 
 Recover a lost device
 =====================
+Users can recover a lost device found in a waste dump by following the
+process of :ref:`checking device authenticity`.
+
+A Devicehub participating in the global record of devices (explained
+in :ref:`checking device authenticity`) automatically uploads public
+device information into Evrythng. If the device was previously
+registered in another Devicehub and there is no record of trading
+between Devicehubs, Evrythng warns both systems. Note that this
+functionality is in development.
 
 Rating a device
 ===============
@@ -35,23 +163,23 @@ action, which includes a guessed **price** for the device.
 There are two ways of rating a device:
 
 1. When processing a computer with Workbench and the Android App.
+   1. While Workbench is processing the machine, the user
+      links the tag with the computer. In this process, as it requires the
+      user to scan the tag with the App, the app allows the user to introduce
+      more information, including the appearance and functionality.
+   2. The App embeds the rate with the device report generated by the
+      Workbench.
+   3. The Workbench uploads the report to Devicehub.
 2. Anytime with the Android App or website.
+   - The user scans the tag of the device with the Android App.
+     After scanning it, the App allows the user to rate the
+     appearance and functionality.
+   - Through the website, the user searches the device and then
+     selects to perform a new :ref:`actions:ManualRate`, rating
+     the appearance and functionality.
 
-When processing a computer with the Workbench, once the user scans the
+In any case, when Devicehub receives the ratings, it computes a final
-tag, it is showed with a screen where it can rate the appearance and
+global :ref:`actions:Rate`, embedding a guessed price for the device.
-functionality. Once done, this data is added to the report of the
-Workbench, which includes the automatic performance grade, and it is
-uploaded to Devicehub, computing the :ref:`actions:Rate` with the
-final total rate and guessed price.
-
-.. todo this is not done yet
-
-The second way is opening the App, scan the tag of the device, and
-then select *rate* to write the appearance and functionality. The
-same process can be done through the website by searching the device.
-Note that with this process there is no way of introducing the
-performance, as it is computed by Workbench, meaning that Devicehub
-takes the last known performance value to compute a new Rate.
 
 Refer to :ref:`actions:Rate` for technical details.
 
@@ -72,9 +200,9 @@ a tag with the App or searching a device through the website,
 and then selecting *create an action*.
 
 Lots are more versatile than actions, and they do not pollute the
-traceability log, which is not needed when placing devices in temporal
+traceability log, which is unneeded when placing devices in temporal
 places like warehouses. Lots act like folders in an Operative System,
-so the user is free to choose what each lot represents, like representing
+so the user is free to choose what each lot represents —for example
 physical locations. For example:
 
 - Lot company ACME
@@ -86,14 +214,20 @@ physical locations. For example:
       - Computer 1
       - Monitor 2
 
-Users create lots through the website or App, selecting *create lot*,
+To create a lot the user uses the webiste or App, selecting *create lot*
-and then can place devices as they were files and folders. With the
+and giving it a name.
-App users can select multiple devices and move all of them to a lot.
 
-To look for devices users reduce the area to look for them by
+To place devices inside a lot through the website, the user selects
-checking to which lot the device is. And then, they visually check
+the devices, it presses *add to lot*, and writes the name of the lot.
-the identifier printed in the tags of devices in that place
+To place them through the App, the user scans the tags of the devices,
-to find the ones they are looking for.
+it presses *add to lot*, and writes the name of the lot.
+
+To look for devices the user reduces the area to look for them by
+checking to which lot the device is. This is done through the website
+or App by searching the device and checking to which lots is inside,
+or searching the lot and checking which devices are inside. And then,
+the user visually checks the identifier printed in the tags of devices
+that are in that specific place until finding the one.
 
 Erasing data and obtaining a certificate
 ========================================
@@ -101,7 +235,7 @@ Erasing data and obtaining a certificate
 .. todo add a reference that explains how Workbench works in general
 
 Workbench erases data storage units, once the user configured Workbench
-to do so. In the configuration users parameterize the erasure to
+to do so. In the configuration users parametrize the erasure to
 follow their desired erasure standard (which involves selecting
 erasure steps, data written or verification, for example).
 
@@ -126,8 +260,8 @@ Delivery
 device. When an user performs a Receive, it means that another user took
 the device physically, confirming reception.
 
-To perform this action scan the tag of the devices with the App,
+To perform this action the user scans the tag of the devices with the App,
-or search it through the website, and select *actions* > *Receive*,
+or search it through the website, and selects *actions* > *Receive*,
 filling information about the receiver and delivery.
 
 An exemplifying case is delivering a device from the warehouse to
@@ -169,9 +303,6 @@ Devicehub guesses the price.
 
 Share device information
 ========================
-
-.. todo explain too lot sharing to users?
-
 Users can generate public links to share with external users, like
 retailers or donors, so they can see a subset of the metadata. Thanks
 to this, external users can audit the devices (donors, consumers), take
@@ -184,9 +315,9 @@ the traceability log.
 
 To share devices:
 
-1. Users scan their tags with the Android App or searches them through
+1. The user scan the tags of the devices it wants to share with the
-   the website.
+   Android App or searches the devices through the website.
-2. They select *generate sharing links*, which gives them a list of
+2. The user select *generate sharing links*, which gives it a list of
    public links of the devices.
 3. Users send those links to their contacts using their preferred
    method, like e-mail.
@@ -195,7 +326,7 @@ To share devices:
 
 Public information of a device is always accessible when an user
 scans the QR of the tag through its smartphone, as the QR contains
-a public link of the device. This ways people in contact with the
+a public link of the device. This way people in physical contact with the
 device, like consumers, can always check information about the device.
 
 Manage sale with buyer (reserve, outgoing lots, sell, receive)
@@ -203,57 +334,54 @@ Manage sale with buyer (reserve, outgoing lots, sell, receive)
 We exemplify the use of lots and actions to manage sales with
 a buyer.
 
-
 1. The first step on sales is for a seller to showcase the devices
    to potential customers by :ref:`sharing them <share device information>`.
 2. A customer inquires about the devices, for example through e-mail.
 3. This can imply a reservation process.
    In such case, the seller can perform the action :ref:`actions:Reserve`,
    which reserves the selected devices for the customer.
-   To perform that action, users scan the tags of the devices
+   To perform that action, the user scan the tags of the devices
    with the App or search them through the website, select them,
    and click *actions* > *Reserve*.
 2. Reservations can be cancelled but not modified, as they are saved
    in the private traceability log of the devices. To cancel a
-   reservation users use the App or the web to select the devices,
+   reservation the user uses the App or the web to select the devices,
    and look for their reservation to cancel it. Note that reservations
    are never deleted, but marked as cancelled.
 3. A reservation is fulfilled once the customer buys, gets through, or rents
    a device; for example by an e-commerce or through a confirmation e-mail.
-   To perform any of those actions, sellers select the devices and click
+   To perform any of those actions, a seller selects the devices and clicks
-   *actions* > *Sell*, *Donate*, or *Rent*. They can perform those actions
+   *actions* > *Sell*, *Donate*, or *Rent*. It can perform those actions
    over devices that are not reserved, or mix reserved devices with
    non-reserved devices. Refer to :ref:`actions:Trade`
    to know more about selling, donating, and renting.
 4. Lots help sellers in keeping an order in sales. A good ordering is
    creating a lot called ``Sales``, and then, inside that lot,
    a lot for each sales, or a lot for each customer.
-5. Devices have to be transported to the customer. Please refer to
+5. The seller gets confirmation from the warehouse or refurbisher
-   the :ref:`delivery` process for more info.
+   that the devices have :ref:`been prepared for use <has been prepared for use>`.
-
+5. Devices are :ref:`delivery <transported>` to the customer.
 
 Verify refurbishment of a device through the tag
 ================================================
 
 .. todo called Verify refurbishment of end-user's device
 
-Devicehub and eReuse.org allows usage of the :ref:`tags: Photochromic tags`
+Devicehub and eReuse.org allows usage of the :ref:`tags:Photochromic tags`
 to visually assist users, at-a-glance, in verifying correctly non-fraudulent
 refurbishing of a device.
 
-As the tags do not provide any technology that links them to a
+Users like refurbishers stick the tags on the devices.
-specific device, they are just stuck on devices.
 
 On the end-user side:
 
-1. End-users buy second-hand devices from retailers.
+1. The end-user wants to verify refurbishment from a device of a retailer.
-2. End-users can apply a more throughout validation or learn about
+2. The End-user sees a QR in a tag, like the the :ref:`tags:eTag`,
-   the life-cycle of the device by scanning the ID tag, the tag
+   which scans with its smartphone's QR reader app, taking the
-   with a QR and/or an NFC, taking the user with the public information
+   user to the :ref:`Share device information <public web page of the device>`.
-   of the device (see :ref:`Share device information`.
 3. The public web page contains, along information about the device,
-   instructions on how to check the validity of the Photochromic tag,
+   instructions on how to check the validity of the Photochromic tag
-   consisting on illuminating the tag with the smartphone's lantern
+   — consisting on illuminating the tag with the smartphone's lantern
    during a minimum of 6 seconds.
 
 Delivery or pickup from buyer after use
@@ -270,6 +398,28 @@ physically received, and a :ref:`Trade` to state the change of
 property. These actions can be performed by scanning the tag with
 the App or by manually searching the device through the website.
 
+Dispose a device
+================
+Users can manage the disposal of devices in Devicehub. A disposal
+in Devicehub means two things: 1) trading devices to a company that
+manages its 2) final destruction or recovery.
+
+The first case is managed by the actions
+:ref:`actions:ToDisposeProduct, DisposeProduct`:
+
+1. An user marks a device to be disposed by scanning the tag of the
+   device or searching it through the website and selecting
+   *actions* > *ToDisposeProduct*.
+2. When the organization in charge of the disposition takes the device
+   the user performs *actions* > *DisposeProduct*.
+
+.. todo when takes the devices (receive?) or when agreed (trade)?
+
+The latter case is managed by the actions
+:ref:`actions:DisposeWaste, Recover`. The user performs the action
+*DisposeWaste* when the product has been destroyed and put into waste,
+and *Recover* when the product has been recycled.
+
 Retail and distribution
 ***********************
 
@@ -281,51 +431,19 @@ the devices to potential customers. Please refer to
 
 Manage purchase of devices with refurbisher / ITAD
 ==================================================
-
+Please refer to :ref:`Manage sale with buyer`.
-.. todo this is not available as for now
-
-Retailers and distributors can reserve devices that are shared to them
-by the refurbishers.
-
-Una entidad puede reservar dispositivos compartidos a través de la plataforma seguiendo los siguientes pasos:
-
-Para ello, navegue al lote eReuseCAT de la entidad que ha compartido los dispositivos.
-Dentro de este lote, navegue al lote de la donación
-Escoge los dispositivos que quiera reservar
-Haga el evento RESERVE para reservar los dispositivos
-La entidad que ha compartido los dispositivo recibirá un email. Para terminar la venta, ambos entidades gestionan la reserva.
-
 
 Distribution of devices
 =======================
-.. es exactamente lo que ya he explicado, las únicas diferencias son
+Please refer to :ref:`Delivery or pickup from buyer after use`.
-   ad-hoc de ereuse cat.
-
-
-Enviar un email con los dispositivos disponibles incluyendo los IDs y los precios a las posibles entidades receptoras (compradores) o bien subir los dispositivos a una tienda online (e-commerce)
-La entidad receptora escoge unos dispositivos y hace un pedido especificando los IDs de los dispositivos escogidos
-Finalizar facturas y convenios con la entidad receptora
-La receptora hace el pago de 100% de la factura
-Hacer el evento SELL sobre los dispositivos para formalizar la venta
-Preparar los dispositivos para entrega
-Confirmar fecha y lugar de la entrega
-Entregar dispositivos y hacer el evento RECEIVE para formalizar la entrega
-Venta en colaboración con entidades comercializadoras:
-
-​Compartir los dispositivos con las entidades especificas o con todo el circuito​
-Una entidad comercializadora reserva los dispositivos​
-La entidad comercializadora y receptora gestionan la reserva​
-
-https://reutilitza-cat.gitbook.io/preguntes-frequents/como-vender-un-dispositivo
-https://nextcloud.pangea.org/index.php/s/V04IMZMt4Jlxmiv/preview
 
 Transport between service providers and buyers
 ==============================================
-??
+Please refer to :ref:`Delivery or pickup from buyer after use`.
 
 Estimate selling price
 ======================
-??
+Please refer to :ref:`Value (price) devices`.
 
 Manage donations and interactions with donors
 =============================================
@@ -344,9 +462,25 @@ Or better said: How to handle after sales issues
 Provide hardware warranty
 =========================
 
-
 Recyclers
 *********
 
 Get the certification for recycling
 ===================================
+Please see :ref:`Dispose a device`.
+
+Device reuse management
+***********************
+
+Pick-up at donor
+================
+Please see :ref:`Manage donations and interactions with donors`.
+
+Transfer donations to refurbishers
+==================================
+
+Get internal custody chain report for donation
+==============================================
+
+View public custody chain for present devices
+=============================================