Taming iButton Keys with Flipper Zero

iButton is a generic name for an electronic identification key packed in a coin-shaped metal container. It is also called Dallas Touch Memory or contact memory. Even though it is often wrongly referred to as a “magnetic” key, there is nothing magnetic in it. In fact, a full-fledged microchip operating on a digital protocol is hidden inside.

In this article, we investigate iButton keys’ configuration from its physics to protocols along with the tricks that can be performed on them with Flipper Zero’s help.

What is iButton?

Usually, iButton implies the physical form of the key and reader - a round coin with two contacts. For the frame surrounding it, there are lots of variations from the most common plastic holder with a hole to rings, pendants, etc.

The Reader

When the key reaches the reader, the contacts come to touch and the key is powered to transmit its ID. Sometimes the key is not read immediately because the contact PSD of an intercom is larger than it should be. So the outer contours of the key and the reader couldn't touch. If that's the case, you'll have to press the key over one of the walls of the reader.

The iButton coin form factor is used not only for common keys with ID but also in climate sensors, devices storing cryptographic keys with inbuilt battery, clock and other cool stuff. Despite having the same appearance as a usual key, these devices can be absolutely different.

How iButton works in Flipper Zero

Developing iButton pad for Flipper Zero was a painful experience. The main problem was the absence of pads for simultaneous reading and emulation on the market. If we used any of the existing solutions, a massive metal button would be sticking out of Flipper with an equally huge reading area next to it. This would have tremendously increased the size of the device.

Therefore we had to invent our own pad design from scratch, so it could be implemented on a PCB without increasing Flipper’s dimensions. Finally, the decision was to use 3 spring-loaded pogo pins. About 20 different designs were tested until the right one was found.

The greatest difficulty in designing the contact pad is emulation: when the flipper itself acts as a key and must be applied to an intercom. Each manufacturer comes up with their own form of the reader so there are always intercoms incompatible with the design: the pins simply do not reach either the central Data + contact or the side GND contact.

The final iButton pad design successfully reads 100% of the keys. Approximately 80% of the readers work successfully with emulation. In the remaining 20% of the readers, it needs some time to reach the reader contacts correctly. In these rare cases, you can use the external GPIO pins, to which the iButton pins are brought out: connect with breadboard wires and poke them into the reader.

Read mode

In Read Mode Flipper is waiting for the iButton key to touch and is able to digest any of three types of keys: Dallas, Cyfral, and Metakom. Flipper will figure out the type of the key itself. The name of the key protocol will be displayed on the screen above the ID number.

To read the key, go to the iButton -> Read menu and bring it to the contact pad. Now the key can be immediately emulated, copied to the memory, or saved to an SD card. Although the contact pad is located on another side of the screen, you can quickly get the hang of reading the keys without turning Flipper.

iButton emulation mode

In the emulation mode, Flipper itself acts as a key and emulates the iButton from the memory. An ID for emulation can be added in Flipper Zero in two ways:

• Read an existing key - saves the key’s ID to an SD card for the desired key to be selected at any time.
• Manually enter the key’s ID - even if you don't have the key on you, provided its ID is known, you can input it manually. For example, you can take a photo of the key’s ID and send it to your friend who owns a Flipper without the hassle of sending the physical key itself.

To launch the emulation go to the iButton -> Saved menu, select the desired key and run Emulate. An inscription with the key ID will appear on the screen. After that, you can bring Flipper to the reader. It is important to remember that this mode uses different pins on Flipper’s pad.

In the emulation mode, Flipper transmits a specific ID and emulates only one predefined key protocol, so it can only be used on the intercom which knows this key. It is impossible to iterate over several keys at once in this mode since it is impossible to make sure whether the intercom has read our key or to know the intercom’s delay between the reading error. Therefore, for a home, office, summer residence, basement, you will need to select a respective key from the menu each time.

iButton via external GPIO

The iButton contact on the back surface has another route in the GPIO nest. This is helpful when connecting to non-standard readers, keys, any devices operating on the 1-Wire protocol like sensors. We use these pins to analyze signals through an oscilloscope. At the same time, this pin is not entirely simple GPIO. It has a pull-up to 5V.

1-Wire protocol

Dallas keys exchange data using the 1-wire protocol.  With only one contact for data transfer (!!) in both directions, from master to slave and vice versa. The 1-wire protocol works according to the Master-Slave model. In this topology, the Master always initiates communication and the Slave follows its instructions.

When the key (Slave) contacts the intercom (Master), the chip inside the key turns on, powered by the intercom, and the key is initialized. Following that the intercom requests the key ID. Next, we will look up this process in more detail.

Flipper can work both in Master and Slave modes. In the key reading mode, Flipper acts as a reader this is to say it works as a Master. And in the key emulation mode, the flipper pretends to be a key, it is in the Slave mode.

Dallas Key Data Format

The intercom receives 8 bytes (64 bits) of information from the iButton to decide whether to open the door or not.

The data structure of these 8 bytes is as follows:

• 1 byte - Family Code, for iButton it is always 0x01
• 6 bytes - serial number of the key
• 1 byte - CRC checksum

The family code for Dallas keys is always 0x01. If your code is different, then most probably it is not a key to the intercom.

In some cases, the serial number is engraved on the key, but it can:

• Contain not all of the 8 bytes
• Have a required sequence of written backward
• Have no clear place of the beginning

The picture above contains a non-obvious example of engraving an ID on an original iButton key. In this case, you need to read bytes from right to left, the checksum is written on the left, and the family code is placed on the right.

Read errors

If the key is read incorrectly, Flipper Zero reports errors. Possible mistakes are:

• Invalid checksum - CRC error
• Wrong family code - if the family code is different from 0x01, Flipper swears that it is not an iButton key.

Inputting ID manually

With the key ID known, you can input it manually into Flipper. This can be convenient when the physical key isn't with you. As an example, you can simply send the necessary bytes in a message or share a photo with a friend. The video below shows the process of creating a new 2-byte Cyfral key. The newly generated key is saved to the SD card.

When creating a key, you need to select its type: Dallas, Cyfral, or Metacom. The length of the ID and the protocol used for emulation are dependent on this. After the ID is input, Flipper will offer to enter a name for the new key or use the generated one.

Writing 1-Wire Dallas Keys

There are Dallas keys that can be written and which cannot. Popular rewritable iButton blanks: RW1990, TM2004, TM01C. The recording process has some nuances, so let's analyze them.

Writing to an empty key may require a higher voltage - for example, not especially popular RW2000 requires a voltage of 8 V (although this is Cyfral, the meaning is clear).

Some keys may require finalization - after finalization, the key can no longer be overwritten. Using this method quite a few intercoms try to overwrite the key before reading it to avoid fake keys. Usually, a voltage pulse and a special command are used for finalization, which may differ for different keys.

Some blanks can fit all types of keys: Dallas / Cyfral / Metakom. Flipper is taught to record the most popular of them.

In order to write a key ID to a "blank", select the desired key from the iButton -> Saved -> Key_name menu and select the Write item. Next, press the rewritable key against the contact pad. When writing is done, Flipper checks the recording and displays a message about the successful writing of the ID.

Native Russian keys: Cyfral and Metakom

The protocols of Metakom and Cyfral were developed in Russia and are widely spread only in the post-soviet countries. Unlike Dallas keys, instead of voltage, they work with the current. These are less common and more expensive keys. They are very sensitive to the parameters of the key (frequency, current strength, signal amplitude, etc.), and duplicating them can be a tricky process. Cyfral and Metakom accept no commands. When power is applied to the key, it immediately starts sending the ID endlessly due to the change in resistance. Thus, the logic levels are determined by the resistance of the switch. According to their documentation, it is conventionally assumed that the information words of the code are given out starting from the least significant bit.

Cyfral

Logic levels in Cyfral, as well as in Dallas, have time limits: if the resistance remains low for about 50 µs, this is a logical “0”, 100 µs stands for a logical “1”.

The transmitted data format is very specific.

Cyfral sends 9 nibbles (1 nibble = 4 bits) cyclically: 1 for the start and 8 for ID. Nibble can have a total of 4 values for the ID and one value for the start word. All other possible inputs are invalid.

As a result, the ID is contained in 2 bytes (8 nibbles ID of a total. 4 nibbles = 16 states = 1 byte of information).

It might happen that Cyfral intercoms are submitting incorrect data while checking the key. Cyfral has no checksums. If you want to make sure of the integrity of the ID, read the key again, and again as many times as you want. Since the signal is analog, it requires an ADC or comparator to be read. The easiest solution here is to use a comparator that gives an output of low or high voltage.

In practice, no problems occur with key emulation. A shorting to ground (absence of a sufficient resistance) is quite enough for the key to give a logical "0".

Metakom

The Metakom key sends out 4 bytes. Each byte ends with a parity bit. Metakom has 3 transfer primitives:

• Sync bit
• Bit 0
• Bit 1

The structure of the parcel looks like this:

• Sync bit
• 4 bytes of information, where each byte contains:
• 1 parity bit 
• 7 data bits

These intercom hones in 99% of cases can be opened with an easily googlable universal key.

1-Wire through an oscilloscope

The transmission line is arranged according to the principle of a "Wired-AND bus" with an open drain (when the state of the whole bus is governed by a “0”-state of any slave) and can have one of two states: logical "0" and logical "1".

Devices (keys and intercom) have internal transistors that pull the line to zero at the right time. The entire transmission line changes to the state of logical "0" if any of the devices turned it to zero. This is to say that if the intercom has pulled the line to zero, the key will know about it, and vice versa.

With the help of voltage constrictions and holding the levels, 1-wire has 4 primitives for working on the bus:

• reset pulse (RESET)
• presence pulse (PRESENCE)
• send bit 0
• sending bit 1 (the same as reading the bit)

That’s how Flipper Zero reads a key: the search command checks if there is Dallas key and then reads the ID. This is made to avoid random coincidences with other Cyfral / Metakom keys, the timings of which may appear to be the same as the required ones.

The oscillogram shows a long signal of 2 commands, where each consists of:

• Command initialization: Reset pulse + Presence impulse
• Command to Slave
• Slave's response to the received command

Let's have a closer look at each of the stages.

The reset sequence consists of two pulses:

1. Reset pulse
2. Presence pulse

For the Reset Pulse, the Master (intercom) pulls the line to the ground. For the Impulse of Presence - the Slave (key) pulls the line to the ground. Some intercoms don't transmit a reset pulse, since the absence of contact between the key and the intercom is taken as the reset signal.

After the initialization command, information is exchanged:

• sending a command to Slave
• Slave response to the command

The exchange is carried out by time slots: one time slot for one bit of information. Data is transferred bit by bit, starting with the least significant bit of the least significant byte. Synchronization of Master and Slave is done in one act: Master (intercom) pulls the line to a low level. Then, after a specific time, Master or Slave measures the voltage on the line and writes a bit of information (Master - when reading the key, Slave - when writing the key). The timing rules for Read and Write commands are the same. Each time slot is synchronized independently, so the transmission of information can be suspended without causing errors.

All signals must have specific time limits! On occasion, the manufacturers of intercoms have the inspiration to create quite exotic time delays.

The iButton also has an Overdrive mode, in which time delays are reduced for the transfer of information to happen faster. Legends tell that in the wild intercoms are operating in this mode... Yet in practice, they have not been encountered.

Standard commands for 1-wire Dallas keys

For iButton it is common to have 1 byte (8 bits) sized commands. Usually, the intercom uses the Search and Read ID commands (Search ROM and Read ROM).

But some manufacturers of intercoms trying to be extravagant come up with different sequences of commands to check whether a key (and not an emulator) is being shown to the intercom.

Therefore, let's take a look at the existing commands. The standard iButton commands for Regular mode the following:

Bonus round: intercom keys

Why are old intercoms bad?

Some old Dallas intercom have an incomplete ID database in their memory. Empty fields contain some values, sometimes corresponding to all zeros (0x00) or all ones (0xFF). To check the intercom for such a failure, two keys are used: one with all zeros, the other with all ones. These keys contain an incorrect family code (not 0x01) and checksum (CRC)!!! - Yes, this can happen.

How do postmen bring advertisements into the building?

No way, postmen deliver letters :) The post office doesn't possess a pile of keys for every single entrance. They normally use universal keys which are suitable for a group of intercoms in an area like all-terrain vehicles. This key can be one per city, one per group of houses, it can be default for some model, or it can be absent altogether.

What is a master key?

Usually, this is a key that does not open the door itself but allows new keys to be added to memory. It is recorded in a separate memory area of ​​the intercom. Such a key can be a master key for some intercoms and a usual one for others at the same time. These are just values recorded somewhere in ​​the intercom memory.

Blocked the intercom while playing around?

This may happen if your intercom has a “blocking key”. It blocks the intercom for all other keys until it is unlocked with the master one.

Blank keys we know

In the course of working with iButton, we recorded some “blank” keys to the table bellow. You are welcome to use it!

Pre-order Now

Our first priority is to fulfill all Kickstarter orders, so our backers will get the first production batch.

If you missed our Kickstarter campaign, you can pre-order now and get your device in Fall 2021, as soon as the second batch is ready. Your pre-orders help us to plan the production and logistics.