---json
{
  "name": "Adding a sensor"
}
---
====== Adding a new sensor ======

A step-by-step walkthrough for adding a sensor that Axiom doesn't recognise. You find it on the bus, add a profile from the catalogue, install it and check that Axiom now claims the device.

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

This example adds an **AHT20** temperature and humidity sensor at I²C address ''0x38''. The AHT20 is in the catalogue but isn't built into the current Device Library firmware. The same steps work for any sensor that has a catalogue profile. If yours doesn't, see [[axiom:device_library:advanced_json|Writing device profiles]].

Before you start, work through [[axiom:device_library:getting_started|Getting started]] so your Axiom has Device Library firmware.

===== Connect the sensor =====

  - Switch Axiom off before connecting or disconnecting a sensor.
  - Connect the sensor, then switch Axiom on and plug it into your computer over USB.
  - Open the Device Library and click **Connect Axiom via USB**.

It helps to know your sensor's I²C address. You can find it in the sensor's datasheet or in the **Addr** column of the **Catalogue**.

===== Scan the bus =====

Open the **Test & tune** tab and click **Scan bus**. The table lists every address Axiom found:

  * **claimed**: a profile recognised the device. The **Resolved type** column shows which one, and **Origin** says whether it is ''built-in'' or ''yours''.
  * **unclaimed**: something answered at this address, but no profile recognised it. Your new sensor should appear here, e.g. ''0x38 … unclaimed … nothing claimed this address''.
  * **direct** rows are Axiom's own internal devices, such as its LEDs and power system. They aren't on the I²C bus.

If your sensor's address isn't in the list at all, Axiom can't see it. Check the wiring and the address before going further. See [[axiom:device_library:troubleshooting|Troubleshooting]].

===== Add a profile to your draft =====

Click **Find catalogue candidates**. For each unclaimed address, the Device Library lists catalogue profiles that use that address. For ''0x38'' it suggests AHT20:

  * **Try AHT20** asks the device the profile's identification question, if the profile has one. It talks to the real device but installs nothing.
  * **Add AHT20 to draft** copies the profile into your draft.

<note>
==A shared address is not proof==
Many different chips use the same I²C address. A candidate means "this profile uses this address", not "this is your device". Check the part number on your sensor.
</note>

You can also add profiles from the **Catalogue** tab. Search by name, maker, class or address, then click **Add to draft**:

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

Either way, the page confirms //AHT20 added to your draft. Nothing has been sent to Axiom yet.//

===== Review and write to Axiom =====

Open the **Install** tab.

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

  * **What will change** compares your draft with the library file on Axiom. Here there is one change: ''add AHT20: new type at 0x38 — nothing built in claims it''. The footer shows how much of Axiom's library space the draft uses.
  * **The write** shows the file that will be written, its size, and what Axiom will have afterwards.

Tick **I have reviewed what will be written and am ready to restart Axiom**, then click **Write to Axiom**. The page confirms //Written to Axiom. Restart it to start using this library.//

<note type="warning">
==The draft replaces the whole library==
**Write to Axiom** replaces the entire library file with your draft. Anything on Axiom that isn't in your draft is removed. If Axiom already has a library you want to keep, first click **Use Axiom's library as draft** on the **Install** tab, then add your new profile.
</note>

===== Restart Axiom =====

Writing doesn't change the profiles Axiom is using yet. Click **Restart Axiom**. The page waits for Axiom to restart and then reads its state again.

If USB stops responding after the restart, unplug Axiom and plug it back in, click **Connect Axiom via USB** and then **Refresh device**.

===== Check the result =====

The status strip should now show ''In use · 1 added · 0 disabled''. On the **Install** tab, **What Axiom did with the file it has** shows what Axiom made of the library when it started:

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

  * **added** counts the profiles Axiom accepted.
  * **disabled** counts the device types you switched off.
  * **rejected** counts the entries Axiom refused. If it isn't 0, the page shows the first error. Fix that entry in your draft and write again.

Finally, go back to **Test & tune** and click **Scan bus**. The sensor's address should now be **claimed** by your profile, with origin **yours**. After a restart, Axiom can take up to a minute to finish finding its devices, so if the address still shows as unclaimed, wait a little and scan again:

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

Click **Start readings** to see the latest values from each device. Click **Stop readings** when you've finished. See [[axiom:device_library:test_and_tune|Testing and tuning devices]] for more.

<note type="tip">
==It's claimed. Does that mean it works?==
A claimed address means a profile matched the device, not that every reading is right. Compare a few readings with what you expect (e.g. room temperature) before relying on a new profile.
</note>

Next: [[axiom:device_library:customise_and_disable|Customising and disabling built-in devices]].