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

Fixes for common problems with the Axiom Device Library: connecting over USB, sensors that aren't detected, profiles Axiom refuses, and getting back to a working state.

===== Connecting =====

==== The Connect button doesn't work, or there's no port to choose ====

  * Use **Google Chrome** or **Microsoft Edge** on a desktop or laptop computer. Other browsers, phones and tablets can't connect over USB.
  * The Device Library connects over **USB only**. It can't use Bluetooth.
  * Try a different USB cable. Some cables only carry power.

==== "Axiom did not answer over USB" ====

Another page or program is probably using Axiom's USB connection.

  - Close other tabs using Axiom, such as the Axiom app or the web updater, and any serial monitor programs.
  - Unplug Axiom, plug it back in, and click **Connect Axiom via USB** again.

==== "This Axiom's firmware does not support the device library" ====

Axiom needs Device Library firmware. Install it from the web updater (see [[axiom:device_library:getting_started|Getting started]]), then connect again.

==== USB stopped responding after a restart ====

Restarting Axiom can occasionally leave the USB connection unresponsive. Unplug Axiom, plug it back in, click **Connect Axiom via USB**, then **Refresh device**. Never assume an interrupted action worked: refresh and check Axiom's state first.

===== Devices =====

==== My sensor doesn't appear when I scan the bus ====

If there's no row at the sensor's address in **Test & tune → Scan bus**, Axiom can't see the device at all. No profile will fix that.

  * Switch Axiom off, check the wiring and connections, then switch it on and scan again.
  * Check the sensor's I²C address in its datasheet. Some boards have jumpers or pads that change it.
  * Check the sensor is getting power.

==== My sensor appears but is "unclaimed" ====

Axiom can see something at that address, but no profile recognises it. Click **Find catalogue candidates**, or add or write a profile. See [[axiom:device_library:add_a_sensor|Adding a new sensor]].

==== My sensor is claimed by the wrong type ====

Different chips can share an address.

  * If a **built-in** profile claimed it, add your own profile for the device. Yours is tried first. Give it a ''detectionValues'' check that tells the two apart.
  * If **your** profile claimed something it shouldn't have, its ''detectionValues'' is probably empty or too loose. Empty means "anything at this address". See [[axiom:device_library:advanced_json|Writing device profiles]].
  * If you don't use a built-in type at all, you can disable it. See [[axiom:device_library:customise_and_disable|Customising and disabling]].

==== I installed a profile but nothing changed ====

  * Did you restart? The status strip shows //Written — restart to apply// until you click **Restart Axiom**.
  * Give it a minute. Straight after a restart, Axiom may still be finding its devices. Wait a little, then **Scan bus** again.
  * Check **Install → What Axiom did with the file it has**. If **rejected** isn't 0, the page shows the first error.
  * For a customised built-in profile, the built-in version is still tried if yours doesn't identify the device. Check **Origin** on the **Test & tune** tab: it should say **yours**.

==== The readings look wrong ====

A claimed device means a profile matched it, not that the decoding is right. Check ''resp.b'' and the attribute keys (''t'', ''at'', ''m'', ''s'', ''d'', ''a'') against the datasheet. See [[axiom:device_library:advanced_json|Writing device profiles]].

===== Installing =====

==== "Your Axiom refused 1 entry: …" ====

Axiom rejected at least one profile when it started. Other profiles in the same file may still have been accepted. Fix the entry named in the error in **Advanced JSON**, then write and restart again. Common causes:

  * the profile uses an address reserved for Axiom's own hardware, such as ''0x36''
  * ''deviceType'' doesn't match the entry's name
  * the library has more profiles, or more bytes, than Axiom allows (the **Install** tab shows both limits)

==== The Check messages say something is wrong ====

Check messages in the editor are advice. They don't stop you writing, and Axiom may accept something the checks warn about, or the other way round. What Axiom reports after restarting is the final word.

==== Another app stopped getting data ====

If you left live readings running in the Device Library, click **Stop readings** and **Disconnect** before using another app with Axiom.

===== Getting back to a working state =====

If Axiom isn't behaving after a library change, open the **Install** tab and click **Remove library & restart**. Axiom goes back to its built-in profiles. Then re-install a library you know works, from an exported file. See [[axiom:device_library:backup_and_updates|Backing up, sharing and removing your library]].

Don't reformat Axiom's storage to remove a library. That erases other files too.

===== Still stuck? =====

Email [[mailto:support@robotical.io|support@robotical.io]] and include:

  * your Axiom firmware version
  * the sensor model and its I²C address
  * the **Raw bus state** from the **Test & tune** tab
  * the messages shown on the **Install** tab
  * your library file, from **Export Axiom's library**