I would like to report on what we have learned during our research into ATJ21XX-SoCs.

Have you ever come across a device such as AGPTEK, WOLFANG, YOTON, or RUIZU? These devices seem to all be built by the same company. All of them support MP3/OGG/FLAC/AAC/APE formats, have the same menu structures, and sometimes even may be capable of playing videos or count your steps.

We have confirmed that RUIZU and AGPTEK are the same company. That's written right on the box, but many other players use the same chip, the ATJ2157 from Actions Semiconductor. These OEMs do not start with just the data sheet but instead use an SDK based on uC/OS-II.

It is unfortunate that some of these devices are built so cheap – low-speed memory, a poor FM tuner, and random glitches in the OEM operating system lead to devices with little polish, given that these chips are very powerful.

• ATJ212X are MIPS-based and were found in your SanDisk Clip Sport and Jam devices as well as the RUIZU X02 (see Ruizu X02 Partial Disassembly and Notes). The data sheet calls the available SRAM “from ten to several hundred KB”.

• ATJ215X are ARM Cortex M4F-based and are now used in almost all “budget” devices. CPU runs at 288MHz and has only 224KB RAM. This is less than the Raspberry Pi RP2040 with 256K.

These chips are all-in-one SoCs – lithium-ion battery protection, microphone input, USB 2.0 interface, SPI and SD interfaces, NOR/NAND flash controller, many GPIO pins, stereo headphone output for headphones, I²S up to 192kHz.

The SDK for the MIPS version was leaked – https://github.com/Suber/PD196_ATJ2127, and we can look into the wonders of UI built on an RTOS. Apart from data sheets and pinouts, we have found nothing for the ARM variant, which is unfortunate. We can buy chips on Alibaba, maybe then we can get SDK?

With such a rich set of supported media and so much versatility in a small package, an open SDK would allow users to address various software shortcomings with these devices (such as the strange fonts I mentioned earlier) or issues related to metadata processing where file names and order are incorrectly displayed.

So far, we have only been able to correct font types and adjust embedded string entries in the .STY files. While searching for information online, we found some repositories dealing with the device flashing process:

• https://github.com/nfd/atj2127decrypt (Re-implementing the flash process)
• https://github.com/Rockbox/rockbox (Implementing unpacking with atjboottool)

People from Rockbox have checked whether a custom operating system can be integrated into https://forums.rockbox.org/index.php?topic=51281.0, but 200K is simply too small.

We also found some people selling proprietary Actions Semiconductor firmware tools for ATJ2127 on a Chinese website that we do not want to include here, but you can find them.

Looking for ADFUS.BIN? PD196ATJ2127 has ADFUS.BIN inside case/fwpkg/US212ADEMO.fw sqlite3 database after you decrypt it with atjboottool for ATJ2127 and the ARM version of ADFUS.BIN is in all ATJ2157 firmwares you can download from RUIZU, AGPTEK etc.

SELECT writefile(FileName, File) FROM FileTable WHERE FileName = 'ADFUS.BIN';

Updates:

1. Somebody got much further than us with arbitrary code execution – https://www.reddit.com/r/hacking/comments/1hss4k3/i_finally_got_arbitrary_code_running_on_ruizu_x02/ and patched AP – https://gitlab.com/reverse2682701/ruizu-x02-rev
2. A post showing how to flash SanDisk Sport using reverse-engineered Actions Media Tool scripts from the repo we linked earlier – https://gist.github.com/roman-yepishev/737dfda3a0a853fe730286d3ce49fccd. The author links to a reverse-engineered ADFUS.BIN but you don't have to do that – take PD196_ATJ2127 version.

Regardless of what's your take on Apple, they do make products that are beautiful. Beauty in design, beauty in simplicity. As I am typing this on my Macbook, I see crisp fonts, I see gorgeous icons.

Now, mass-produced gadgets from China usually lack that design fine-tuning even when the hardware is amazing.

Starting from serif fonts which make your 24-bit FLAC-playing DAP look like it is a typewriter from 90s, to the hodgepodge of icons and backgrounds.

Usually these devices do not support customer theming, but we are going to change this a bit with Waterjet.

In the coming months we will be releasing docs and tools allowing decrypting, unpacking, updating, and re-packing firmware resources for devices running on Actions Semiconductor ATJ212X, ATJ215X, and others that use μC/OS-based SDK, allowing everytone to personalize their devices without the need for SDK from Actions.

And to the vendors who ship these devices — you will have a better customer experience if you run the fonts and designs past a designer, then we would not need to do all this.

And to start us up, here's the format of FWIMAGE.FW for ATJ212X devices.

Actions Semiconductor FWIMAGE.FW Specification

1. File Structure

The firmware image is a sector-based container (512 bytes per sector) with a fixed-size header area of 16 sectors (8192 bytes).

Section	Size	Description
Global Header	512 bytes	Basic metadata (Magic, VID/PID, Ver)
LDIR Table	240 * 32 bytes	Fixed-size Logical Directory entries for all files
Component Data	Variable	Raw binary data for drivers, APs, and STY files

2. Global Header (Sector 0)

The first 512 bytes contain the system metadata.

Offset	Size	Description
0x00	4	Magic: 0x0FF0AA55
0x04	4	SDK Version (ASCII)
0x08	4	Firmware Version (ASCII)
0x0C	2	Vendor ID (VID)
0x0E	2	Product ID (PID)
0x10	4	LDIR Checksum (Stride 4)
0x50	48	USB Setup Info (ASCII)
0x80	336	SDK Description (ASCII)
0x1FA	4	R3 Config Sector Offset (Pointer to DEVINFO.BIN)
0x1FE	2	Global Header Checksum (Sum of first 510 bytes)

3. Logical Directory (LDIR) Table

Starting at offset 0x200 (Sector 1) and ending at 0x2000 (Sector 16). This is a static table of exactly 240 entries. Unused entries are null-padded.

Offset	Size	Description
0x00	8	Filename (8.3 format, space padded)
0x08	3	Extension (ASCII)
0x0B	5	Padding
0x10	4	Sector Offset: Start position in sectors (absolute position = offset * 512)
0x14	4	File Size: Size in bytes
0x18	4	Reserved
0x1C	4	File Checksum (Stride 4 sums)

4. Checksums

Global Header Checksum

The last two bytes of the Sector 0 header (offset 0x1FE) contain a 16-bit checksum of the first 510 bytes using a 2-byte stride.

uint16_t calculate_header_checksum(const uint8_t *data, size_t len) {
    uint16_t sum = 0;
    for (size_t i = 0; i < len; i += 2) {
        uint16_t val = (uint16_t)data[i] | ((uint16_t)data[i+1] << 8);
        sum += val;
    }
    return sum;
}

LDIR & File Checksum Algorithm (Stride 4)

Accumulates 32-bit words interpretated as little-endian. The sum naturally wraps at 32 bits.

#include <stdint.h>
#include <stddef.h>

/**
 * Calculates the Actions Stride-4 checksum.
 * @param data Pointer to the buffer (must be 4-byte aligned for some platforms)
 * @param len  Length of data in bytes (should be multiple of 4)
 * @return 32-bit unsigned checksum
 */
uint32_t calculate_checksum_s4(const uint8_t *data, size_t len) {
    uint32_t sum = 0;
    for (size_t i = 0; i < len; i += 4) {
        uint32_t val = (uint32_t)data[i] |
                       ((uint32_t)data[i+1] << 8) |
                       ((uint32_t)data[i+2] << 16) |
                       ((uint32_t)data[i+3] << 24);
        sum += val;
    }
    return sum;
}

Sector Alignment

Every file within the image must start on a 512-byte boundary. When packing, files must be padded with null bytes to reach the next sector.

Boot Sequence

The firmware expects KERNEL.DRV and CONFIG.BIN to be present at specific LDIR indices or offsets defined by bootloader. Just put them at the same location as where you took them.

---

Interested in the format of ATJ215X firmware? It is an encrypted sqlite3 database. And encryption has already been reverse-engineered — see rockbox sources for atjboottool.

I bought one so you don't have to. (Edit: at least until Eaton supports Matter over WiFi)

These devices connect to Azure IOT Platform. While I am sure Eaton has a great deal for that, it means that every time I turn the lights on or off, Azure gets paid a small amount of money.

The switch, while not multi-touch capable, will wait 0.5s before turning the load on or off.

In an event of a network connection disruption, when you are back online the switch will take ~5 minutes to become available in the app. There is no local control even though the ESP32-C3-MINI1 (datasheet) module can do this. The unit is provisioned with WiFi credentials over Bluetooth but other than that Bluetooth is not used.

And when you use schedules, the status LED does not correspond to the actual state of the switch.

I am still debating whether to give Schneider Electric Matter-over-WiFi a try, but the more I read the specs the more I become convinced that Z-Wave network I already have is the best.

Edit: https://www.eaton.com/us/en-us/products/wiring-devices-connectivity/Matter.html suggests that at some point these WiFi devices will gain Matter support. If/when that happens, these switches, dimmers, and receptacles will become much more useful.

In case you want more #IOT in your life, Eaton ships remotely actuated circuit breakers.

The breakers are provisioned using a “BlinkUp” system through your phone. You start the provisioning on your device, then put your screen to the sensor on the circuit breaker, your screen blinks a number of times sending WiFi credentials to the device, and then the latter connects to the Electric Imp servers. Eaton is using impOs as the basis of their offering, and Electric Imp is adamant they are secure.

Now, Eaton provides API to these circuit breakers – https://api.em.eaton.com/docs, but there is no true local access – there is apparently a way to get local control, but your device must phone home weekly to receive configuration that would allow you to talk to your device locally.

As I was writing this I decided to scan GitHub for the URLs I found so far, and, well, people smarter than me have already written a home_assistant integration against #SEW, but it is a bit different from what I saw in the field:

• https://github.com/cnecrea/hidroelectrica

I'd still like to describe how to locate the endpoints and the login process, so here we go...

This is the second post about #SEW SCM API – Smart Customer Mobile API by Smart Energy Water, this time we will learn about different APIs using real world utility websites.

It appears that there are at least two different API “flavors”. The one that uses ModuleName.svc/MethodNameMob naming convention and usually resides under PortalService endpoint, and the newer one, which lives under /API/.

So e.g. Nebraska Public Power District has endpoints at https://onlineaccount.nppd.com/PortalService/, e.g. https://onlineaccount.nppd.com/PortalService/UserLogin.svc/help. Rochester Public Utilities runs a different set of endpoints, with the root at https://connectwith.rpu.com/api.

The endpoints for the latter API can also be browsed at https://scmcx.smartcmobile.com/API/Help/.

Different utilities pay for different set of modules, and here's some of the modules I have discovered so far:

• AdminBilling
• CompareSpending
• ConnectMe
• EnergyEfficiency
• Generation
• Notifications
• Outage
• PaymentGateway
• Usage
• UserAccount
• UserLogin

For /PortalService/ endpoints you can visit BASE_URL + /PortalService/ + ModuleName + .svc + /help to get the list of RPC calls you can issue. In order to find out what to send in the requests, you need to look into the calls within the apps for your utility. Note that some utilities opted out of the AES/CBC/PKCS5Padding PasswordPassword encryption, so let's hope this will be a trend forward. Currently SEW web portals talk to a completely different set of APIs to populate the interface, even though they are querying the same thing.

So to start, here's how to login to your favorite utility:

from typing import Mapping, Any

import base64
import json
import hashlib
import requests
import urllib.parse

from Crypto.Cipher import AES

BASE_URL = "https://example.com/PortalService"


def _encrypt_query(
    params: Mapping[str, str], encryption_key: str = "PasswordPassword"
) -> str:
    """Encrypt with AES/CBC/PKCS5Padding."""
    cipher = AES.new(encryption_key, AES.MODE_CBC, IV=encryption_key)

    cleartext = urllib.parse.urlencode(params).encode()

    # PKCS5 Padding - https://www.rfc-editor.org/rfc/rfc8018#appendix-B.2.5
    padding_length = 16 - len(cleartext) % 16
    cleartext += padding_length * chr(padding_length).encode()

    return base64.b64encode(cipher.encrypt(cleartext)).decode("ascii")


def request(module: str, method: str, data: Mapping[str, Any]) -> Mapping[str, str]:
    enc_query = _encrypt_query(data)
    # Or module + '.svc/'
    url = BASE_URL + "/" + module + "/" + method

    resp = requests.post(url, json={"EncType": "A", "EncQuery": enc_query})
    if not resp.ok:
        raise Exception(resp.status_code)
    return resp.json()


password_digest = hashlib.sha256("PASSWORD".encode()).hexdigest()
# Or ValidateUserLoginMob
response = request(
    "UserLogin",
    "ValidateUserLogin",
    {"UserId": "USERNAME", "Password": password_digest},
)
print(response)

response will contain some object, you will need LoginToken and AccountNumber to proceed with most of the other calls.

It's a bit awkward that different utilities have different endpoints, which makes creating a universal client challenging, so for now I am researching the ways to get info from the Usage module. The parameters are weird (“type”: “MI”, or “HourlyType”: “H”), but we will get there.

Once upon a time I learned about Opower HomeAssistant integration. But my utility does not use Opower, it was using something called “Smart Energy Water”.

Smart Energy Water, or #SEW is a SaaS provider, and they ship the whole thing – the backend, frontend, and the phone apps, the latter under the name SCM, which means Smart Customer Mobile.

So I embarked on a journey to figure out how these phone apps worked and, if successful, get my data out and into homeassistant.

APK

I pulled an APK of my utility from Google Play Store and found that something secret is hidden in a libnative-lib.so binary, under com.sew.scm.gcm.SecureConstant, under a few methods returning String, and some methods that decrypt these strings using a heavily obfuscated set of routines, which essentially XOR'd (in case of Android APK) the values of gcm_default_sender_id + google_app_id + Android_App_RatingConstant_File, all the values from the strings.xml within the app resources.

One of the decoded tokens contains a key for request encryption. It was ...

PasswordPassword

SCM apps use private APIs. In order to remain private and hard to use the requests are encrypted.

You urlencode the parameters into key=value&key1=value1... form, then encrypt the resulting string using AES-CBC with PKCS5 Padding (16 bytes variant) using PasswordPassword as both the key and IV.

Then you send {"EncType": "A", "EncQuery": "base64-encoded-encrypted-string"}, and receive response from one of the .../API/Module/MethodName endpoints. The response will be JSON with no extra encryption, so it is definitely a deterrent against making requests, not a security feature.

Login

Armed with that knowledge, and some help from exposed API listing on one of the utility websites I found that I need to use ValidateUserLoginMob call expecting userid and password.

However, password had to be base64-encoded result of applying a secret scheme from that SecurityConstant module above. It is always SHA256.

So my first https://utility.example.net/API/UserLogin/ValidateUserLogin was a success, I got LoginToken and AccountNumber, which was all we needed to start poking APIs.

Tada!

If your utility uses SEW SCM, i.e. one of these at https://play.google.com/store/apps/developer?id=Smart+Energy+Water, you should be able to get API listing by visiting the web interface, and appending /API/Help. Or, if your utility runs an older version of SCM, replace /portal/ with /portalservice/UserLogin.svc/help or /portalservice/Usage.svc/help. You may get the .NET API definitions.