PetKit Custom Integration

From what I can see in Home Assistant logs it does seem to send passive data but very sporadically, anywhere from (very roughly) 15 - 45 minutes apart. I have found killing the app and reconnecting forces the data to update which makes sense (and is handy for testing) and leads me on to my next question…

Regarding your comment below instead of a BLE integration would it be possible to force or emulate a connection to the app eg every 5 or 10 minutes to get consistent data?

    1. I have not investigated if the fountain advertises its data passively, but I’d assume an active connection is required since, even with petkit’s BLE relay, an active connection to the fountain is made before any data is sent to the relay device. It would also explain why the PetKit app won’t update any fountain data / notify you about the water level being empty unless it is open and establishes an active connection to the water fountain.*

The integration already emulates what the app does: uses another PetKit device as a BLE relay (via the cloud) when connecting remotely. Regarding timing: the next release will include a higher period of time between BLE relay initiations and even a separate option for users to change it if they want to. From my own testing with different polling intervals over the past several months, their water fountains are just inconsistent with data, no way around it. I’ve even encountered using their app to connect directly (no BLE relay) to the water fountain and it states that water is running when physically I can see the water fountain is completely out of water.

1 Like

Where can I find this project to flash a petlibro fountain with esphome?

Any progress on the yumshare integration? Let me know if you need help/tester! Thanks!

Hello @RobertD502

First off - great job making a custom integration for PetKit! I’m choosing a smart litterbox to use and I’m wondering if I should get Petkit PuraMax 2 :slight_smile:

Second off - there are some devices marked as “new” on PetKit’s site:
PetKit PuraMax 2 PETKIT PuraMax 2
Eversweet Max PETKIT EverSweet Max Cordless Smart Pet Drinking Fountain like faucet dockstream water dispenser for cat and dog Portable Cat Waterer Rabbit Waterer
and YumShare feeders.

Do you plan to add support for these devices? If you do, how soon can we expect it? I want to decide for the devices for my cat and you’re the deciding factor! :smiley:

@RobertD502 @wrobelda you using new ESPHome firmware config from @tmfinnell for Petlibro?

UPDATE: See now that @tmfinnell and others been discussing ESPHome for Petlibro products here:

hi is there any update on the petkit yumshare support? i just bought the dual hopper and it doesn’t seem to be picking it up. i have two - a solo and a dual hopper. only the solo is working. thanks

I took some inspiration from your script as well as @RobertD502 's library, plus a metric ton of packet sniffing, and managed build a relatively simple python library around it, to expose most of the controls to MQTT, to enable HA’s MQTT Discovery.

It supports connecting to the W5-family of Petkit Water Fountains via Bluetooth Low Energy, without any Petkit WiFi enabled products.

There’s a few caveats, in terms of the secret being exchanged with the device, and scheduling of Do Not Disturb as well as Lights Out. Hopefully I get around to address the last two - but will have a hard time fixing (correct) generation of secrets, as I only have two devices and thus not nearly enough to reverse engineer the algorithm used.

So, for a bit of shameless self-promotion and plugging, you can find the library here, should it tickle your fancy: PetkitW5BLEMQTT

1 Like

Hey wow. Cool. Thank you for providing it. I don’t know anything about coding so I used ChatGPT to help. Is what ChatGPT tells me correct?

Beginner-Friendly Guide to Setting Up PetkitW5BLEMQTT in Home Assistant

If you’re new to Home Assistant and not familiar with coding, follow these simple steps to integrate your Petkit W5 device.


1. Preparation

  • Ensure that Home Assistant is running on your device.
  • You’ll need access to the Home Assistant Web Interface and Supervisor.
  • Enable the MQTT Integration in Home Assistant:
    1. Go to SettingsIntegrations in Home Assistant.
    2. Search for MQTT and set it up (if not already configured).

2. Download the Petkit Adapter

  • PetkitW5BLEMQTT is not a ready-to-use add-on, you need to manually set it up:
  • Install the Samba Add-on to enable file sharing between your PC and Home Assistant.
  • Configure Samba, start it, and connect to Home Assistant from your PC. Instructions are available here.

3. Upload the Required Files

  1. Download the repository files from GitHub:
    • On the GitHub page, click CodeDownload ZIP.
    • Extract the ZIP file on your computer.
  2. Upload the entire extracted folder to the Home Assistant config folder:
    • Use Samba to copy the files from your PC, or
    • Use the File Editor add-on in Home Assistant to upload and manage files directly.

4. Configure the Settings

  1. Open the file config.yaml from the uploaded folder.

    • If you’re using the File Editor in Home Assistant, you can edit the file directly.
    • Add your MQTT details and Petkit device information:
      mqtt:
        host: "Your MQTT server address (e.g., Home Assistant IP)"
        port: 1883
        username: "Your MQTT username"
        password: "Your MQTT password"
      
      petkit:
        devices:
          - name: "Petkit Water Fountain"
            mac: "MAC address of your Petkit device"
      
    • MAC address: You can find the MAC address in the Petkit app or your router’s list of connected devices.
  2. Save the file.


5. Start the Petkit Service

  • Currently, you need to run the program manually:
    1. Open Terminal & SSH in Home Assistant (install it via the Add-On Store if necessary).
    2. Run the following command:
      python3 /config/PetkitW5BLEMQTT/petkit_w5_mqtt.py
      
    3. Leave the terminal open so the program keeps running in the background.

6. Display Data in Home Assistant

  1. Add an MQTT sensor to Home Assistant:
    • Go to SettingsDevices & ServicesMQTT.
    • Check if new topics appear (e.g., petkit/water_status).
  2. Configure a sensor manually:
    • Open your configuration.yaml file and add:
      sensor:
        - platform: mqtt
          name: "Petkit Water Level"
          state_topic: "petkit/water_status"
      
  3. Restart Home Assistant to apply the changes.

7. Create Automations

Now that the sensor is available, you can set up automations, such as notifications when the water level is low:

  • Go to SettingsAutomations and create a rule.
1 Like

I think ChatGPT might have overengineered it a bit :sweat_smile:

I believe these steps, should get you going:

git clone https://github.com/slespersen/PetkitW5BLEMQTT.git
ln -s $(pwd)/PetkitW5BLEMQTT /path/to/your/python/site-packages/PetkitW5BLEMQTT

Change the path to the correct, for your python site-packages directory. You can find the path this way:
python -c "import site; print(site.getsitepackages())"

To find the address of your petkit device, you can run this command:
bluetoothctl scan le

PetKit devices will be prefixed with “Petkit” in the name

Afterwards you run the script this way:
python main.py --address "A1:B2:C3:D4:E5:F6" --mqtt --mqtt_broker "broker.example.com" --mqtt_port 1883 --mqtt_user "user" --mqtt_password "password" --logging_level "INFO"

Remeber to change the arguments to suit your environment.

I’ll be adding a systemd service file in the future, until then the script can be run inside screen to achieve session persistency.

Please note - as the secret is not implemented, you will need to restart the script after the first run, to ensure that the non-compliant secret has been set to the device. This will stop the app from working, until power has been cycled!

Thank you for your quick reply. I will wait until the system service file is ready :slight_smile:

It’s been added :slight_smile:

Remember to change the variables in the systemd service file, so it corresponds to your setup.

Yes i’ve started my own integration and i support Dual Hopper and camera feature :slight_smile:

You can use it here :

Great work! You can likely figure out the secret generation by reverse engineering the Bluetooth communication code within the PetKit app.

1 Like

Thanks - and sorry for hijacking your thread. Seemed like the right place to highlight it to the ones chasing a pure BLE integration :slight_smile:

I’ve been through the app code multiple times, but it seems they’re generating the secret on the server side and delivering it as a response to the signup function within W5BleClient – the call consists of Serial Number, MAC address and the Device ID.

The security on the API seems rather … missing - so at some point I’ll try and write a script for poking at their API with data I’ve authored, in order to see if it’ll eat anything and hopefully derive their algorithm.

Not a problem at all. Interesting info….I haven’t looked into it, but I know that no info about the secret is transmitted to the initiating device (phone) when using the BLE relay function - my assumption is that the API is called and the server talks to the relaying device itself which is told what command to execute and the secret. Sniffing the communication between server and relay device on your network would be too complicated for the majority of users, so I don’t see grabbing the secret in this method being very useful.

Couple of questions come to mind:

Have you tried hooking into the app and seeing the exact data that is being transmitted/how it is being built along the way from phone to server? I guess the response could be captured by re-doing the registration process, but that wouldn’t be very user friendly and wouldn’t give us any info about what is going on server-side.

Have you investigated, when dealing with a reset water fountain that isn’t associated with an account/hasn’t been set up, if it can be used without needing to send a secret to it? Or, does the water fountain expect to go through a setup process? If it can be used when not associated with a PETKIT account, then users can remove/reset their water fountain(s) from their PETKIT account and rely solely on Home Assistant for controlling it/them.

1 Like

I used to use the PetKit Integration with my PuraMax. However, after recently purchasing a new Element Solo auto feeder and adding it to the PetKit app, I noticed that the integration couldn’t discover the new feeder.

May I know how can I add the new PetKit device in HomeAssistant through the integration? Many thanks

Is it this feeder? If so, simply reloading the integration should discover the feeder.

Hi

Yes, it’s the feeder I bought
After I reloaded the integration, there’re still 2 devices only. One is PuraMax and one is my Pet.
Am I missing something?
Thanks a lot.

Screenshot 2024-12-28 at 12.08.09

I’ve been through the code a couple of times, after intercepting the traffic using HTTP Toolkit and dumping the Bluetooth communication to btsnoop_hci.log (analyzed using Wireshark) – replicating the API calls is no issue at all, and the response is consistent across multiple calls with the same Serial Number, MAC and Device ID. The biggest concern in that regard, is the traffic being transferred using HTTP.

The entire initialization process seems to be transparent to the user, and happen in the background as part of the “Connecting to device” screen in the app.

It’s specifically the command 73 that sets the secret, and thus initializes the device - which is sent after 213, which retrieves the device ID for the API call to w5/signup.

I’ve tried with non-initialized water fountains, but they disconnect if command 73 is not issued, and thus not setting a secret. When the secret has been set, the connection initialization skips command 73 and goes directly to 213, 86 (contains the secret in bytes 3-8) and then 84 setting the date and time.

Device will respond to 86 with either a 1 or 0 – which seems to indicate if the secret was correct or not. This can be circumvented if the device has not been registered and thus not received the correct secret, or if 73 is reissued with a new secret - with the caveat that the app will not communicate with the device, unless its been power cycled.

Unfortunately there is no simultaneous use of the BLE connection, as the device stops advertising when a connection has been established - so regardless of the secret, the app and the library cannot be used at the same time.