# Pipup

**Repository Path**: supergame/Pipup

## Basic Information

- **Project Name**: Pipup
- **Description**: 在Android设备开启一个常驻服务。其它设备可以向其发出http请求，然后该Android设备会以悬浮窗方式弹出一个网页。可用于展示摄像头画面（go2rtc的stream.html）等。

情景：
门外有人按门铃，中控安卓平板弹出显示门外摄像头画面。这个过程可能需要 Home Assistant 的自动化 + go2rtc 转 rtsp 流。
甚至可以双向通话(需 webrtc)


- **Primary Language**: Unknown
- **License**: LGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-06-10
- **Last Updated**: 2026-06-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PiPup

PiPup 是一款允许用户在 Android 设备(TV/平板/手机)上显示自定义画面的应用程序。

该应用程序最常见的用途是将来自智能家居系统的通知/内容发送到您的 Android 设备。

![](./graphics/screenshot-1.jpg)

__一些示例场景：__

- 在 Android 设备上显示摄像头快照图片（例如检测到动静）
- 当有人在您家门口时，显示摄像头视频画面
- 当您的烘干机/洗衣机完成时，发送通知
- 您可能觉得有用的其他功能

_重要提示：安装/更新后，建议您重启Android设备并打开应用一次，以确保后台服务正在运行。_

#### 注意：

在 Android TV（8.0+）上，您需要用 adb 命令手动设置 SYSTEM_ALERT_WINDOW 权限（没有设置界面）

要授予应用程序绘制叠加层的必要权限，您需要运行以下命令：

```
adb shell appops set nl.rogro82.pipup SYSTEM_ALERT_WINDOW allow
```

## 集成

PiPup 使用一个运行在 7979 端口的嵌入式 Web 服务器 (NanoHTTPD)。

### 发送通知

#### 要发送包含外部媒体资源（图像、URL 或 WebView）的通知，请使用 application/json。

| 属性 | 值 |
| ------------- | ---------------- |
| Path:         | /notify          |
| Method:       | POST             |
| Content-Type: | application/json |

示例 JSON 数据：
```json
{
  "duration": 30,
  "position": 0,
  "title": "你的标题",
  "titleColor": "#0066cc",
  "titleSize": 20,
  "message": "你想显示的内容..",
  "messageColor": "#000000",
  "messageSize": 14,
  "backgroundColor": "#ffffff",
  "media": {
    "image": {
      "uri": "https://mir-s3-cdn-cf.behance.net/project_modules/max_1200/cfcc3137009463.5731d08bd66a1.png",
      "width": 480
    }
  }
}
```

所有字段均为可选，`media` 可以指定 3 种类型：
```json
{ "image": { "uri": "address_to_your_image", "width": 480 }}
{ "video": { "uri": "address_to_your_video", "width": 480 }}
{ "web": { "uri": "address_to_your_resource", "width": 640, "height": 480 }}

```

#### 要发送带有图像文件的通知，请使用 multipart/form-data

| 属性 | 值 |
| ------------- | ------------------- |
| Path:         | /notify             |
| Method:       | POST                |
| Content-Type: | multipart/form-data |

表单字段：

| 字段 | 类型 |
| --------------- | -------------------------------------------- |
| duration        | Integer (default=30)                         |
| position        | Integer (0..4, default=0)                    |
| title           | String                                       |
| titleSize       | Integer (default=16)                         |
| titleColor      | string (default=#FFFFFF, format=[AA]RRGGBB   |
| message         | String                                       |
| messageSize     | Integer (default=12)                         |
| messageColor    | String (default=#FFFFFF, format=[AA]RRGGBB   |
| backgroundColor | String (default=#CC000000, format=[AA]RRGGBB |
| image           | File                                         |
| imageWidth      | Integer (default=480)                        |

`position` 是一个枚举值，取值范围为 0 到 4

| | 位置 |
| -----: | ----------- |
| 0 | 右上角 |
| 1 | 左上角 |
| 2 | 右下角 |
| 3 | 左下角 |
| 4 | 居中 |

颜色属性采用 `[AA]RRGGBB` 格式，其中 alpha 通道是可选的，例如 #FFFFFF 或 #CCFFFFFF


# Home Assistant 实现按门铃自动推送摄像头画面到 Android

## 前置要求
HA 已安装 go2rtc addon，且 go2rtc 已经接入摄像头流

## 步骤
1、Android 上安装 pipup.apk  
如果是 Android TV，需通过 adb 连接运行命令：
```
adb shell appops set nl.rogro82.pipup SYSTEM_ALERT_WINDOW allow
```
命令主要是让 pipup 能够显示在其他应用上层（切记一定要赋予权限）

2、打开刚刚安装的 pipup  
应该会显示服务已运行<IP地址:7979>，意思是在 pipup 服务在 Android 的 7979 端口运行

3、在 HA 的 `configuration.yaml` 文件中添加一行：  
```
rest_command: !include rest_commands.yaml
```
然后在 HA 的 config 根目录下新建 `rest_commands.yaml` 文件

4、将下面的代码粘贴到 `rest_commands.yaml` 文件中，记得修改其中的IP地址为你 Android 设备的 IP  
```yaml
 pipup_image_on_android:
  url: http://Android设备的IP:7979/notify
  content_type: 'application/json'
  verify_ssl: false
  method: 'post'
  timeout: 20
  payload: >
    {
      "duration": {{ duration | default(20) }},
      "position": {{ position | default(0) }},
      "title": "{{ title | default('') }}",
      "titleColor": "{{ titleColor | default('#50BFF2') }}",
      "titleSize": {{ titleSize | default(10) }},
      "message": "{{ message }}",
      "messageColor": "{{ messageColor | default('#fbf5f5') }}",
      "messageSize": {{ messageSize | default(14) }},
      "backgroundColor": "{{ backgroundColor | default('#0f0e0e') }}",
      "media": { 
        "image": {
          "uri": "{{ url }}",
          "width": {{ width | default(640) }}
        }
      }
    }
 
pipup_url_on_android:
  url: http://Android设备的IP:7979/notify
  content_type: 'application/json'
  verify_ssl: false
  method: 'post'
  timeout: 20
  payload: >
    {
      "duration": {{ duration | default(20) }},
      "position": {{ position | default(0) }},
      "title": "{{ title | default('') }}",
      "titleColor": "{{ titleColor | default('#50BFF2') }}",
      "titleSize": {{ titleSize | default(10) }},
      "message": "{{ message }}",
      "messageColor": "{{ messageColor | default('#fbf5f5') }}",
      "messageSize": {{ messageSize | default(14) }},
      "backgroundColor": "{{ backgroundColor | default('#0f0e0e') }}",
      "media": { 
        "web": {
          "uri": "{{ url }}", 
          "width": {{ width | default(640) }},
          "height": {{ height | default(480) }}
        }
      }
    }
```

5、修改完配置文件后重启HA  
重启后，到 HA 开发者工具的服务里应该能够找到 `rest_command.pipup_image_on_android` 和 `rest_command.pipup_url_on_android` 这2个服务。
其中前者是可以推送图片到 Android 设备，后者是可以推送视频链接到 Android 设备；

6、接下来写一个自动化来触发推送：  
```yaml
description: "按门铃时推送摄像头画面到 Android"
mode: single
triggers: # 改成你自己的触发条件
  - trigger: state
    entity_id:
      - event.xxxxxx
actions:
  - action: rest_command.pipup_url_on_android
    data:
      title: 门口
      message: 有人按门铃
      width: 2500
      height: 1600
      duration: 50
      url: http://HA的IP:1984/stream.html?src=my_camera1 # 1984 是 go2rtc 的端口。my_camera1 是你在 go2rtc 上配置的摄像头流
```