Mycila JSY App ⚡️📡

An Arduino / ESP32 web application for Shenzhen Jiansiyan (JSY) electricity meters (single-phase and three-phase). Mycila JSY App reads JSY series meters (JSY1031, JSY-MK-163, JSY-MK-193, JSY-MK-194, JSY-MK-227, JSY-MK-229, JSY-MK-333 from https://www.jsypowermeter.com) and exposes a web dashboard, UDP broadcast stream, and a set of REST endpoints. It can also emulate Shelly EM and Shelly 3EM REST APIs so home automation platforms that speak Shelly devices can integrate with JSY meters.

Mycila JSY App is built using the Mycila JSY library for JSY meter communication and the Mycila ESPConnect library for WiFi connectivity management.

Latest Release GPLv3 license Contributor Covenant Build GitHub latest commit

Table of contents

Features

Important: this application can mimic Shelly EM and Shelly 3EM devices (Shelly Gen2 API) so it is easy to integrate into platforms expecting Shelly devices.

Supported JSY models

Downloads

Releases (firmware binaries) are available in the GitHub releases page:

https://github.com/mathieucarbou/MycilaJSYApp/releases

Naming convention:

FYI, Supported ESP32 boards with Ethernet support:

Installation

First-time flash (factory image):

esptool.py erase_flash
esptool.py write_flash 0x0 MycilaJSYApp-BOARD.FACTORY.bin

OTA update (upload via web UI):

  1. Download MycilaJSYApp-BOARD.OTA.bin from Releases
  2. Open http:///update and upload the OTA file
  3. Device reboots

Wiring

After flashing the device the serial pins used for the JSY are printed to the Serial console during boot. The default board pin mappings are in the code and summarized below.

Board Serial2 RX (JSY TX) Serial2 TX (JSY RX) WiFi Ethernet
denky_d4 22 21 ✅ ❌
esp32-c3-devkitc-02 18 19 ✅ ❌
esp32-c6-devkitc-1 4 5 ✅ ❌
esp32-gateway 16 17 ✅ ✅
esp32-poe 35 33 ✅ ✅
esp32-s2-saola-1 18 17 ✅ ❌
esp32-s3-devkitc-1 16 17 ✅ ❌
esp32dev 16 17 ✅ ❌
esp32s3box 19 20 ✅ ❌
lilygo_eth_lite_s3 17 18 ✅ ✅
nodemcu-32s 16 17 ✅ ❌
tinypico 4 25 ✅ ❌
waveshare_esp32s3_eth 19 20 ✅ ✅
wipy3 4 25 ✅ ❌
wt32-eth01 5 17 ✅ ✅

Electric wiring note for 2-channel JSY boards:

How to build your own version

Using PlatformIO (recommended):

PIO_BOARD=esp32dev pio run -e ci

You can override the JSY serial mapping and UDP port using build flags, for example:

PIO_BOARD=esp32dev PLATFORMIO_BUILD_SRC_FLAGS="-DMYCILA_JSY_SERIAL=Serial2 -DMYCILA_JSY_RX=RX2 -DMYCILA_JSY_TX=TX2 -DMYCILA_UDP_PORT=53964" pio run -e ci

Usage

The device also broadcasts JSY data via UDP on port 53964 by default (configurable).

Tip: you can toggle UDP publishing per channel/phase directly from the dashboard (each channel/phase card includes an “UDP Publish” switch). These preferences are saved.

REST API

The following HTTP endpoints are implemented in src/main.cpp (matching the Shelly Gen2 API for EM / 3EM where applicable). Use http://<device-ip> as base.

{
  "enabled": true,
  "time": 2375713792,
  "speed": 9600,
  "address": 1,
  "model": 355,
  "model_name": "JSY-MK-163",
  "frequency": 50.01,
  "voltage": 236.01,
  "current": 6.16,
  "active_power": 1178,
  "reactive_power": 852.8571,
  "apparent_power": 1454.321,
  "power_factor": 0.81,
  "active_energy": 1433820,
  "active_energy_imported": 1101090,
  "active_energy_returned": 332730,
  "resistance": 31.04444,
  "dimmed_voltage": 191.2338,
  "nominal_power": 1794.225,
  "thdi_0": 72.39874
}

Shelly EM and 3EM emulation

The project exposes Shelly-compatible endpoints (Shelly Gen2 API style) so third-party platforms can treat the device as a Shelly EM or Shelly 3EM. The emulation endpoints implemented in src/main.cpp are:

{
  "name": "Mycila JSY App",
  "id": "shellyproem50-40:22:D8:EA:C5:71",
  "mac": "40:22:D8:EA:C5:71",
  "ver": "15.3.9",
  "app": "EM"
}

{
  "id": 0,
  "voltage": 240.2,
  "current": 6.473,
  "act_power": 1327.6,
  "aprt_power": 1557.6,
  "pf": 0.87,
  "freq": 50,
  "calibration": "factory"
}

{ "id": 0, "total_act_energy": 2776175.11, "total_act_ret_energy": 571584.87 }

{
  "id": 0,
  "a_current": 4.029,
  "a_voltage": 236.1,
  "a_act_power": 951.2,
  "a_aprt_power": 951.9,
  "a_pf": 1,
  "a_freq": 50,
  "b_current": 4.027,
  "b_voltage": 236.201,
  "b_act_power": -951.1,
  "b_aprt_power": 951.8,
  "b_pf": 1,
  "b_freq": 50,
  "c_current": 3.03,
  "c_voltage": 236.402,
  "c_active_power": 715.4,
  "c_aprt_power": 716.2,
  "c_pf": 1,
  "c_freq": 50,
  "n_current": 11.029,
  "total_current": 11.083,
  "total_act_power": 2484.782,
  "total_aprt_power": 2486.7,
  "user_calibrated_phase": [],
  "errors": ["phase_sequence"]
}

{
  "id": 0,
  "a_total_act_energy": 0,
  "a_total_act_ret_energy": 0,
  "b_total_act_energy": 0,
  "b_total_act_ret_energy": 0,
  "c_total_act_energy": 0,
  "c_total_act_ret_energy": 0,
  "total_act": 0,
  "total_act_ret": 0
}

Notes about the Shelly endpoints:

UDP broadcast format

For developers

The project uses these libraries (examples shown in src/main.cpp includes):

Other Arduino libraries used (platform-provided): DNSServer, ESP32 Async UDP, ESPmDNS, FS, LittleFS, WiFi, Ticker, Update

Contributing

Patches, issues and suggestions welcome. If you add a Shelly-compatibility improvement, please add test cases and document any behavior differences.

License

This project is licensed under the GNU General Public License v3.0. See the LICENSE file for details.