---json
{
  "name": "Getting started"
}
---
====== Getting started with the Device Library ======

Install Device Library firmware on your Axiom, connect it to the Device Library over USB, and learn what the page is telling you.

{{ :axiom:device_library:devlib-offline.png?nolink&800 |}}

===== Install Device Library firmware =====

The Device Library only works with firmware that supports it. At the time of writing this is **v0.1.16-devlib**. Older versions such as v0.1.3 do not support it.

<note type="warning">
==Already have a custom library?==
A normal firmware update replaces the files stored on Axiom, **including your device library**. Before updating, export it: see [[axiom:device_library:backup_and_updates|Backing up, sharing and removing your library]].
</note>

  - Plug Axiom into your computer with a USB cable.
  - Open the web updater at [[https://updates.robotical.io/axiom/web-updater/|updates.robotical.io/axiom/web-updater]] in Chrome or Edge.
  - Under **Firmware version**, choose the Device Library version (it ends in ''-devlib'' and is normally selected already).
  - Click **Update**. When the browser says the page //wants to connect to a serial port//, choose the option that says **USB JTAG/serial debug unit** or similar, then click **Connect**.
  - Wait until the completion message appears.

===== Open the Device Library and connect =====

  - Open [[https://updates.robotical.io/axiom/web-updater/library.html|updates.robotical.io/axiom/web-updater/library.html]], or choose **Open Device Library** on the web updater page.
  - Close any other tab or app that is using Axiom over USB, such as the Axiom app or the web updater. Only one page can use the USB connection at a time.
  - Click **Connect Axiom via USB**, choose your Axiom in the browser's list and click **Connect**.

When the connection works, the top right of the page shows **USB connected** and a message tells you whether a custom library is installed.

===== Read the status strip =====

The strip below the title tells you about the connected Axiom:

{{ :axiom:device_library:devlib-in-use.png?nolink&800 |}}

^ Field ^ What it shows ^
| **Device** | Which Axiom you are connected to. |
| **State** | ''Built-in devices only'': no custom library. \\ ''In use · 1 added · 0 disabled'': your library is running. \\ ''Written — restart to apply'': your library is on Axiom but won't be used until Axiom restarts. \\ ''Removed — restart to restore built-ins'': the library has been deleted but Axiom is still using it until it restarts. |
| **Library file** | Where the library is stored on Axiom, normally ''/local/devlib.json''. |

Click **Refresh device** at any time to read Axiom's state again. Refreshing is safe: it doesn't change anything on Axiom.

If you see //This Axiom's firmware does not support the device library//, go back to step 1 and install the Device Library firmware, then connect again.

===== Find your way around =====

The page has five tabs:

  * **Devices**: the profiles Axiom can recognise. This tab opens first.
  * **Catalogue**: ready-made profiles you can add to your draft.
  * **Install**: review, write, restart and check the result. The recovery buttons are here too.
  * **Advanced JSON**: your draft as editable JSON, with a built-in descriptor guide.
  * **Test & tune**: scan the bus, live readings and temporary settings.

You don't need Axiom connected to browse the **Catalogue** or to edit your draft in **Advanced JSON**. The page calls this the //Offline workspace//. Your draft is saved in the browser on this computer, so it's still there next time you open the page. To keep a permanent copy, export it (see [[axiom:device_library:backup_and_updates|Backing up]]).

===== When you've finished =====

  * If you started live readings on the **Test & tune** tab, click **Stop readings**.
  * Click **Disconnect** before using Axiom with another app.

Next: [[axiom:device_library:add_a_sensor|Adding a new sensor]].