SerialRenogy

A NodeJS utility to retrieve data from a Renogy solar controllers via RS-232 and serve it as a Prometheus metrics endpoint for display in Grafana.

[!NOTE] This software provides read-only access to your solar controller; you can not change any parameters with this software.

This software is licensed under the MIT License.

Thanks

Most of the credit for this goes to sophienyaa for her NodeRenogy project, on which this is heavily based. If you would prefer to publish data to MQTT instead of scraping via Prometheus, use that one.

From sophienyaa/NodeRenogy:

Thanks to menloparkinnovation the for renogy-rover that inspired this software.

Thanks to the Renogy boards for the Protocol docs.

Thanks to the solaranzeige.de boards for pinout information.

Requirements & Assumptions

1. I have personally tested this with the Renogy Rover 20A MPPT and the Renogy Wanderer 10A PWM controllers. I assume this will work with any Renogy solar controller with an RS-232 or RS-485 port.

2. A Raspberry Pi Zero 2 W is perfect for this -- it's small, low power, very affordable, and plenty powerful to run SerialRenogy. Although, any SBC/PC with a serial (RS-232) port, or an available USB port for adding a USB-to-serial dongle.

3. Linux is recommended. Although SerialRenogy is a NodeJS app, and NodeJS does run on Windows, it hasn't been tested -- if you use Windows, you're on your own.

4. It is assumed that you already have an instance of Prometheus and Grafana running. If not, it is feasible to set those up on the same device as SerialRenogy, however, that procedure is beyond the scope of this guide.

5. It is assumed that you have at least basic experience with general electronics and wiring -- this guide will provide information on making your own serial cable, but it is not a step-by-step component sourcing and assembly guide.

Supported Registers

As of August 2023, this utility supports all known data fields available in the Renogy controller per their own documentation. A copy of this document is available in reference/renogy-serial-protocol.pdf for reference.

[!NOTE] I assume it's okay to share it here since it was originally posted in a public forum by a Renogy employee.

Device information:

Energy data:

"Street Light" Status and Brightness

The term "street light" just means load, except brightness refers to a 0-100% output, which would only be used if the load were a light. Most users will probably ignore the brightness field and just focus on the load status, which will be either on or off.

Charging State

The charging state will be one of these values, based on the solar power coming in and current battery level. Some of these may not apply, depending on whether you have a PWM or a MPPT controller.

Faults

There are currently 15 possible fault conditions, listed below:

For each one of these:

• 0 -> normal
• 1 -> triggered

The current version of this utility does not distinguish which faults are active, it only asserts whether one is set or none at all. An upcoming version will break these out individually.

Connecting the Controller

Renogy controllers use either RS-232 or RS-485 for serial communications, so you will need an interface that supports the protocol your controller uses.

If you're using a standard computer for this, and it has a RS-232 port (usually a DB-9 or DB-25 connector), you're golden. If not, or if you're using a SBC like a Raspberry Pi or similar, you can use a USB-to-serial dongle -- these are plentiful on Amazon and AliExpress, just make sure you get one with a well-known chip from FTDI.

[!CAUTION] The UART pins found on Raspberry Pi's, microcontrollers, etcetera are TTL-serial, which is not the same as RS-232. TTL voltages will be at the host VCC level (3.3 or 5 volts), while RS-232 can be as large as -25V to +25V (although most PCs might be in the -13V to +13V) -- connect RS-232 directly to the UART pins on your Pi or microcontroller and it's likely that you'll let out the magic smoke!

Actually, there is a way to use the UART pins on your Raspberry Pi instead of plugging in a USB-to-serial dongle by wiring a RS232-to-TTL converter, which uses a MAX3232 chip to safely convert the signal levels (here's one on Amazon). Wiring this up is simple, but I'm not going to cover it in this guide.

Do I have to make my own serial cable?

Rumor has it that Renogy used to offer a USB-to-serial cable with a properly wired RJ12 connector, but it is no longer available. Building one is easy, as the components required are readily available and the information on building it can be found anywhere (such as in the section below!).

But there's some good news! I have discovered that some third-party manufacturers/vendors are offering clones on Amazon and AliExpress. These use FTDI chips that are compatible with Windows (driver installation required) and Linux (native kernal support).

Building a cable

The Renogy Rover and Wanderer (and other controllers with a RS-232 port) have a RJ12 jack that it uses for serial communications.

The RJ12 connector on the controller has 6 pins, with the first 3 being needed for our cable (an RJ11 jack won't work because it's missing the first pin). The remaining pins are for power, which we won't need (those are for the BT-1 and BT-2 Bluetooth modules). See the below table for the pinout.

Using the utility

Ideally you would install/run this on a device that is connected to your solar controller all the time. I use a Raspberry Pi Zero W, which is more than powerful enough for this purpose.

You will first need to ensure you have NodeJS v18+ installed on your device.

[!IMPORTANT] If you installed a version of NodeJS via apt-get, please check the version with node -v and ensure it's at least v18 -- some distributions are known to host very old versions of NodeJS, and if that's the case for you, you'll need to uninstall it and install a more recent version manually (more information on that here).

Installation

1. Clone this repository:

   cd /opt
   git clone https://github.com/MaffooClock/SerialRenogy.git

2. Change to the directory you cloned the code into:

   cd /opt/SerialRenogy

3. Install NodeJS dependencies:

   npm install

4. Setup a global executable:

   sudo npm link

Running the utility

Basic Example:

serial-renogy -s /dev/ttyUSB0

This would access the solar controller on serial port /dev/ttyUSB0 and publish a simple web server on default port 9090.

This utility supports additional options as needed, please see the table below for a full list of options:

These options can also be set via environment variables, by prepending SR_ to the argument (e.g. SR_SERIALPORT=/dev/ttyUSB0). This is useful when running as a service (see below section).

Running as a service

Since the main idea of this utility is for it to run all the time, a systemd service file is included. These instructions are for Ubuntu/Debian and other distro's based on that (such as Armbian, DietPi, Raspberry Pi OS).

1. Copy the serial-renogy.service file from the repo into /etc/systemd/system/.

2. Edit the new /etc/systemd/system/serial-renogy.service file to set environment variables as needed.

[!IMPORTANT] This service will run as root since it does not specify a User= and Group=. This could pose a security risk, so if you decide to specify a system user for this service, make sure that user is a member of the dialout system group so that it has access to the serial port.

3. Run the following commands:
   • To start the service:

     systemctl start serial-renogy

   • To check the logs/ensure it's running:

     journalctl -uf serial-renogy

   • To enable the service to run at startup:

     systemctl enable serial-renogy

[!TIP] If you make changes to /etc/systemd/system/serial-renogy.service after it's been started or enabled, you'll need to run systemctl daemon-reload to refresh systemd.

Getting data into Prometheus

It is assumed that if you're considering using this utility, and you know what Prometheus is, then you probably already know what to do. Just add this to your prometheus.yml:

scrape_configs:
   - job_name: 'serial-renogy'
     scrape_interval: 5s
     static_configs:
        - targets: [ 'raspberrypi.local:9090' ]

This will have Prometheus scrape the data from http://raspberrypi.local:9090/metrics every five seconds. Of course, adjust the hostname (or IP address) and TCP port as necessary.

Visualizing data in Grafana

As above, the assumption is that you know what Prometheus is, and therefore likely know what Grafana is, and thus already have your Prometheus instance configured as a data source in Grafana. If not, there are plenty of how-to's on the web that can guide you through setting these up, such as this one.

If you don't already have an instance of Prometheus and Grafana running somewhere, and you're using a relatively new-ish Raspberry Pi or similar SBC with decent CPU/RAM, then you can probably run it on the same host as SerialRenogy (older Raspberry Pi devices, like the original Pi Zero W from 2017, will probably struggle).

Dashboard

You can import the included SerialRenogy.json dashboard file into Grafana to get a good starting point. It uses the Sun and Moon plugin to display the sun's azimuth in some of the charts to make it easy to compare power against the position of the sun, so you'll want to install that plugin first.

As I have a 20A controller with a 12V battery bank in my implementation, all the gauges are configured with that in mind. If your system uses higher or lower voltages or current, of course you'll need to tweak the dashboard to fit.