---json
{
  "name": "Device Library"
}
---
====== Device Library ======

The Axiom Device Library lets you teach Axiom to recognise new I²C sensors and actuators, change how its built-in device profiles behave, and switch off device types you don't want detected. Everything happens in a web browser over USB, without rebuilding or reflashing firmware.

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

===== What you can do =====

  * **See what Axiom recognises.** List every device profile on your Axiom, whether it is built in or one you added.
  * **Add a new device.** Copy a ready-made profile from the online catalogue, or write your own.
  * **Customise a built-in profile.** For example, poll a sensor less often.
  * **Disable a device type** so Axiom stops detecting it.
  * **Test and tune.** Scan the I²C bus, see which profile claimed each address, watch live readings and try settings temporarily.
  * **Back up and share** your library as a JSON file, or reuse it on another Axiom.

===== What you need =====

^ You need ^ Details ^
| An Axiom with Device Library firmware | At the time of writing this is **v0.1.16-devlib**, the default version in the [[https://updates.robotical.io/axiom/web-updater/|Axiom web updater]]. See [[axiom:device_library:getting_started|Getting started]]. |
| A desktop or laptop computer | Windows, Mac, Linux or Chromebook, running **Google Chrome** or **Microsoft Edge**. |
| A USB cable | The Device Library connects over USB only. Bluetooth is not supported. |
| The device you want to use | Its datasheet is useful if you need to write or check a profile. |

Open the Device Library at [[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.

===== How it works =====

Axiom's firmware contains a set of **built-in profiles**. A profile describes one type of device: its I²C address, how to identify it, how to set it up, how often to read it and what the data means. The built-in profiles are always there, and you cannot delete them.

Your changes live in a small **library file** on Axiom (''/local/devlib.json''). It holds three kinds of entry:

  * **Additions:** profiles for devices Axiom doesn't know about.
  * **Customised copies** of built-in profiles. Your copy is tried first, and the built-in profile stays as a fallback.
  * **Disabled types:** device types Axiom should no longer detect.

You build up changes in a **draft**, which is saved in your browser. Nothing reaches Axiom until you choose **Write to Axiom**, and Axiom keeps using its current profiles until you choose **Restart Axiom**. Removing the library file and restarting always takes Axiom back to its built-in profiles.

===== The five tabs =====

^ Tab ^ Use it to ^ Needs Axiom connected? ^
| **Devices** | See every profile Axiom can recognise, view a definition, customise or disable it | Yes |
| **Catalogue** | Search ready-made profiles and add one to your draft | No |
| **Install** | Review what will change, write the library to Axiom, restart, check the result, export or remove the library | Yes |
| **Advanced JSON** | Edit profiles as JSON, create new ones, import and export files | No |
| **Test & tune** | Scan the bus, find profiles for unknown addresses, view readings, change polling temporarily, send test commands | Yes |

===== Guides in this section =====

Work through these in order the first time:

  - [[axiom:device_library:getting_started|Getting started]]: install the firmware, connect Axiom and find your way around.
  - [[axiom:device_library:add_a_sensor|Adding a new sensor]]: a complete walkthrough, from plugging in a sensor to seeing it claimed.
  - [[axiom:device_library:customise_and_disable|Customising and disabling built-in devices]]: change a built-in profile, or stop a device type being detected.
  - [[axiom:device_library:test_and_tune|Testing and tuning devices]]: scan the bus, watch readings and try settings temporarily.
  - [[axiom:device_library:advanced_json|Writing device profiles]]: the profile format and the Advanced JSON editor.
  - [[axiom:device_library:backup_and_updates|Backing up, sharing and removing your library]]: firmware updates, other Axioms and going back to built-ins.
  - [[axiom:device_library:troubleshooting|Troubleshooting]]: connection problems, devices that aren't detected, and refused profiles.

If you get stuck, see [[axiom:device_library:troubleshooting|Troubleshooting]] or email [[mailto:support@robotical.io|support@robotical.io]].