Drunk & Dangerous Friends🍻

：我喝不 Shot 了！：（

Concept Development 專案簡介

在現代聚會、派對、韓國遊戲文化中，「調酒」常作為懲罰或遊戲的一環，而過程中最麻煩的就是——要有人負責調，而且常常調錯、量不準、有爭議，也不夠公平，不夠科技感。 我們希望改善這點，打造一個：

讓使用者透過網頁進行遊戲，由系統調製飲品的人機互動系統 ⭐

Implementation Resources 使用資源

物品名稱	數量	價格(TWD)	照片
raspberry pi4	1個	0
MW明緯 LRS-50-12 電源供應器（AC→DC Power Supply）	1個	290
L289N 馬達驅動器	2個	200
幫浦	4個	400
塑膠管	3米	30
杜邦線數條 (母母、公母線)	數條	0
紅黑線	3米	30
麵包板	1塊	0
銲槍、焊錫	1組	0
AC電源線	1條	0
Type C 充電線	1條	0
角柱	5個	0
紙箱(一大一小)	2個	0
棉花棒	數個	0
膠帶	數個	0
熱融槍	1隻	0
美工刀、剪刀	1個	0
蠟筆	1組	0
標籤紙	數張	0
塑膠小杯	1袋	29
旋轉杯	4個	100
塑膠量杯	5個	225
飲料	5瓶	199
酒	3瓶	0
運費	x	14	無

Existing Library/Software 技術概覽

• Docker (Docker image 、 Docker container)
• RPi.GPIO (0.7.1)
• fastapi (0.115.5)
• uvicorn[standard] (0.32.1)
• pydantic (2.10.3)
• python (3.11-bookworm)

Implementation Process

我們的目的是建立一套「多人派對遊戲 × 自動調酒機」的整合系統。整體流程由玩家端裝置作為操作介面，透過同一個網段連線至樹莓派。樹莓派同時擔任遊戲伺服器（Game Server）與調酒控制模組（Drink Controller），接收玩家操作後進行遊戲邏輯判斷，再輸出對應的硬體控制指令。

在系統架構上，我們先完成網路連線與房間流程：第一位玩家加入房間、鎖上另一個房間、玩家輸入使用者名稱、等待人數到齊、由房主開始遊戲，並透過轉盤決定出手順序與開局設定。接著實作核心遊戲邏輯，以兩顆六面骰作為事件觸發依據，依據不同點數組合對應不同遊戲事件，並支援兩種模式：酒鬼模式（無積分、輸了直接喝、同一人累計喝三杯結束）與闔家歡模式（積分制、房內發生5次喝酒事件即結束）。

在硬體實作部分，樹莓派透過 GPIO 輸出控制訊號，連接至 L298N 馬達驅動多顆幫浦。每一顆幫浦對應到特定 GPIO 腳位與控制通道，系統會將遊戲結果轉換為「酒款（幫浦選擇）＋出酒時間（秒數）」等控制參數，並由控制模組執行倒酒動作。至此，我們完成了從玩家透過網頁互動、伺服器處理，到實體調酒輸出的完整閉環 ~！

System Architecture Diagram 系統流程圖

Functional Map 功能架構圖

Hardware architecture 硬體架構

圖上的顏色代表接線，以紅黑線或杜邦線為主，若是用紅黑線，需將外層的絕緣層先剪開，在進行接線。杜邦線直接使用即可。還是依當下狀況決定使用哪種線材

AC電源線與電源供應器接線表

AC 電源線（需剪線纏接）	圖上接線顏色	LRS-50-12 電源供應器
黑色（火線）	紅色	L
白色（中性線）	藍色	N
綠色（地線）	綠色	綠色（地線）⏚

⚠️ AC 端為 高壓電，實作時需確保斷電後再接線，並做好絕緣處理

AC 直流電內部構造

 L（Live / 火線）：AC 電源的火線，需特別注意安全
 N（Neutral / 中性線）：AC 電源回路
 ⏚（Ground / 接地）：保護接地，務必確實連接

設備共地接線表

裝置 / 來源	位置 / 腳位	圖上接線顏色 (杜邦線)	麵包板位置
LRS-50-12 電源供應器	-V	藍色	負極（藍色線位置）
L298N 腳位第一台	GND	灰色	負極（藍色線位置）
L298N 腳位第二台	GND	淺灰色	負極（藍色線位置）
Raspberry Pi 4	Pin 9	深藍色	負極（藍色線位置）

電源供應器與 L298N 接線表 (提供幫浦電源)

透過 LRS-50-12 電源供應器將交流電(AC)轉為直流電(DC)向 L298N 提供12V的直流電

裝置 / 來源	位置	圖上接線顏色 (紅黑線+杜邦縣頭)	LRS-50-12 電源供應器
L298N 腳位第一台	12V	紅色	V
L298N 腳位第二台	12V	桃紅	V

因為在接線的過程可能會有銅線(紅黑線)插上去L298N不穩的問題，如果遇到這種情況，可以用焊接的方式焊上杜邦線的頭，並用熱縮套管保護起來。

L298N 與 Raspberry Pi GPIO 接線表

幫浦	L298N 第一台	L298N 第二台	圖上接線顏色（杜邦線）	樹莓派實體腳位	GPIO
第一顆幫浦	IN1		深紫色	Pin 16	GPIO 23
	IN2		紫色	Pin15	GPIO 22
第二顆幫浦	IN3		橘色	Pin 13	GPIO 27
	IN4		咖啡色	Pin11	GPIO 17
第三顆幫浦		IN1	深紫色	Pin 35	GPIO 19
		IN2	紫色	Pin33	GPIO 13
第四顆幫浦		IN3	橘色	Pin 29	GPIO 5
		IN4	咖啡色	Pin 31	GPIO 6

L298N如何透過GPIO控制幫浦?

 每顆幫浦由 兩個 IN 腳位 控制（正轉 / 反轉）
 第一台 L298N：控制 第一、第二顆幫浦
 第二台 L298N：控制 第三、第四顆幫浦
 Raspberry Pi 使用 GPIO 編號 進行程式控制
 所有 GND 需與電源供應器、樹梅派「共地」

L298N 與幫浦接線表

幫浦編號	幫浦正負極	圖上接線顏色(杜邦線)	L298N 第一台	L298N 第二台
第一顆幫浦	紅線	橘色	OUT1
	黑線	藍色	OUT2
第二顆幫浦	紅線	粉色	OUT3
	黑線	綠色	OUT4
第三顆幫浦	紅線	橘色		OUT1
	黑線	藍色		OUT2
第四顆幫浦	紅線	粉色		OUT3
	黑線	綠色		OUT4

幫浦一開始只有兩條金屬條(會有一條標示是正極)，需要焊接紅黑線，才可以進行實作。

L298N如何輸出訊號到幫浦?

 OUT1 / OUT2 → 控制同一顆幫浦（正轉 / 反轉）
 OUT3 / OUT4 → 控制另一顆幫浦
 第一台 L298N：控制 第 1、2 顆幫浦
 第二台 L298N：控制 第 3、4 顆幫浦

完成硬體電路接線後，將整組裝入紙箱中，再依需求將幫浦接上適當長度的塑膠管，即可完成調酒機的機台組裝！

在調酒機的正面，我們會將四條輸出管固定並綁在一起，形成一個統一的出口，讓所有飲品從同一位置流出，看起來更整齊也更方便使用。最後，透過遊戲條件觸發幫浦，系統會自動加入指定的酒品，完成整個自動調酒流程。

Knowledge from Lecture

• Raspberry Pi 環境設定

• Linux 腳本與程式設計

• Docker 包裝整個專案

Installation 安裝

在建立這個專案之前，我們需要先確認樹莓派已安裝Raspberry Pi OS（64-bit)(由於 32 bit 沒有測試不確定)，並且要確保電腦與樹梅派在同一個網路環境，接著，為了方便後續操作，我們會先透過遠端方式登入樹莓派，進行相關設定與操作。

ssh [樹梅派主機名稱]@[樹梅派ip]

在樹莓派安裝 Git (可以下載 GitHub 的專案到我們的樹梅派）

在下載之前，我們要先更新一下

sudo apt update

安裝git，並確認是否安裝成功 (看到版本號就代表成功)

sudo apt install git -y

查看git版本

git --version

從 GitHub 下載 cheer 專案

可以在樹梅派中，選擇一個你想存放專案的位置，並進去(在這邊我們選了 home)

cd ~

使用 git clone 下載專案

git clone https://github.com/NCNU-OpenSource/cheer.git

進入專案資料夾

cd cheer

確認專案內容

ls -al 

應該會看到端案列出以下這幾個檔案，代表專案下載成功！

cheer/
├── main.py               # FastAPI
├── game_logic.py 
├── pump_controller.py    # GPIO 控制程式
├── QA.py
├── PartyGame             # 前端網頁
├── requirements.txt
├── Dockerfile
└── .dockerignore

在樹莓派安裝 Docker

:::spoiler 首先要使用docker在樹梅派安裝docker，才可以對我們的專案進行使用

下載並執行官方安裝腳本

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh ./get-docker.sh

設定使用者權限(選擇性)

# 將目前使用者加入 docker 群組
sudo usermod -aG docker $USER

# 重新登入或執行以下命令生效
newgrp docker

# 測試安裝
docker --version

:::

建立容器

確認在cheer底下，執行以下指令建立容器 image：

docker build -t <<建立容器的名稱>> .

<容器名稱> 可以自行命名，例如 cheer

查看我們建立好的image

這樣就能確認剛剛建立的 image 是否存在

docker images 

查看是否有容器正在運行

在啟動遊戲伺服器之前，先檢查你的 Raspberry Pi 是否已有容器在運行，以避免 port 衝突

docker ps -a

-a 的意思是除了正在執行的容器以外，還可以看見隱藏(stop)的程式

執行容器

docker run -d \
     --name <<容器名稱>> \
     --privileged \
     --device /dev/gpiomem:/dev/gpiomem \
     -p 8000:8000 \
     <<容器名稱>>:latest

<容器名稱> 為你建立的 image 名稱，例如 cheer

打開瀏覽器

在瀏覽器輸入：

http://<樹莓派IP>:8000

即可進入遊戲網站並開始使用。 這樣我們的環境就建立好了!!

Usage 使用方法

在執行以下指令前，請先確認已安裝並啟動 Docker 環境。(若沒有請依照下方步驟進行安裝)

如何安裝docker

在樹莓派安裝 Docker

首先要使用docker在樹梅派安裝docker，才可以對我們的專案進行使用

下載並執行官方安裝腳本

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh ./get-docker.sh

設定使用者權限(選擇性)

# 將目前使用者加入 docker 群組
sudo usermod -aG docker $USER

# 重新登入或執行以下命令生效
newgrp docker

# 測試安裝
docker --version

從 docker hub 拉取 image

docker pull lydiaguo/cheer:latest

查看我們 pull 下來的image

這樣就能確認剛剛pull的 image 是否存在

docker images 

查看是否有容器正在運行

在啟動遊戲伺服器之前，先檢查你的 Raspberry Pi 是否已有容器在運行，以避免 port 衝突

docker ps -a

啟動容器

docker run -d \
     --name cheer \
     --privileged \
     --device /dev/gpiomem:/dev/gpiomem \
     -p 8000:8000 \
     cheer:latest

打開瀏覽器

使用者在開始遊戲之前，事先連進與樹梅派同個網路(wifi)，利用自己的設備開啟瀏覽器，並輸入 IP 進入遊戲首頁 在瀏覽器輸入：

http://<樹莓派IP>:8000

進入到首頁後，玩家可以點選開始遊戲，並導入選擇模式介面。遊戲模式主要有兩種，一種是# 進入到首頁後，玩家可以點選開始遊戲，並導入選擇模式介面。遊戲模式主要有兩種，一種是闔家歡模式，一

模式介紹

項目	酒鬼模式	闔家歡模式
模式定位	派對刺激型	互動策略型
是否使用積分	否	是
積分計算方式	不適用	答對 +1、答錯 -1、未抽中 0
回合計算方式	無回合	任一人觸發喝酒事件算一回合
結束條件	任一玩家喝到 3 杯	進行5回合後結束

當玩家進入遊戲選擇了其中一個模式，輸入名字，才能夠進入該模式。

1. 第一位將會成為房主，(如果當前玩家退出，第二個進來的玩家將會自動成為房主)。並且會對另一模式進行上鎖
2. 其他玩家依序加入進行中的模式，需要 2 人(含)以上，房主才能夠選擇是否開始遊戲。在這個模式的房間內，最多只能容納 6 人遊玩。 (看要不要放圖片)
3. 在房主按下開始遊戲前，如果有第 7 位玩家進入，該位玩家會被安排到排隊區(除非房間內的玩家主動退出，其餘等待的玩家才能夠進入房間)。否則若是在房主按下開始遊戲後，原先在排隊的玩家與剩餘想加入的玩家，則會進入觀戰模式，無法加入遊玩。
4. 點選開始遊戲後，房主點選轉輪盤後，系統會自動轉輪盤抽取遊玩的順位，並自動轉至主要遊玩畫面。
5. 依照順位結果，玩家可以在輪到自己時進行操作，其他玩家則觀看並等待。
6. 玩家可以點上方的問號查看規則，進行遊玩的對照。以下是我們兩種模式的遊戲規則。

闔家歡模式｜骰子規則對照表

骰子點數（兩顆相加）	對應組合	遊戲類型	規則說明	積分變化	是否使用幫浦
3	1+2	LSA 問答	手機顯示選擇題，玩家作答	對 +1 / 錯 -1	否
4	1+3	隨機酒	系統隨機指定一種酒	無	是
5	1+4、2+3	LSA 問答	手機顯示選擇題	對 +1 / 錯 -1	否
6	1+5、2+4	黑白切	系統配對，勝負判定	贏 +1 / 輸 -1	否
7	1+6、3+4、2+5	自選酒	玩家自行選擇酒款與比例	無	是
8	2+6、3+5	隨機酒	系統隨機倒酒	無	是
9	3+6、4+5	喝喝	因懲罰過重，補償積分	+1	否
對子	11、22、33、44、55、66	喝喝	補償事件	+1	否
10、11	4+6、5+6	真心話大冒險	完成後可結束事件	無	否

酒鬼模式｜骰子規則對照表

骰子點數（兩顆相加）	對應組合	遊戲類型	規則說明	是否使用幫浦
3	1+2	我有你沒有	系統隨機指定一人與擲骰者對戰，輸的人喝	否
4	1+3	隨機酒	系統隨機指定一種酒	是
5	1+4、2+3	掰手腕	系統隨機配對，輸的人喝	否
6	1+5、2+4	黑白切	系統隨機配對，輸的人喝	否
7	1+6、3+4、2+5	自選酒	擲骰者自行選擇酒款倒酒	是
8	2+6、3+5	隨機酒	系統隨機指定一種酒倒酒	是
9	3+6、4+5	射龍門	撲克牌遊戲，輸的人喝	否
對子	11、22、33、44、55、66	喝喝	無條件喝酒	否
10、11	4+6、5+6	真心話大冒險	完成挑戰，失敗者喝	否

在開局時，系統會先加入第一杯酒，準備開始遊玩，玩家依照順序，點選<<擲骰子的按鈕>>，根據骰子點數觸發對應的小遊戲或事件。(可以看上方規則)

加酒環節

遊戲中加入酒的狀況主要有兩種一種為電腦隨機選，一種為玩家自己選。

加酒模式	說明
電腦選擇	會有四種顏色，分別對應到四種馬達，系統會隨機抽出一種顏色進行加酒
玩家自選	會有四種顏色，分別對應到四種馬達，玩家可以自己選一種顏色加入酒

遊戲結束條件

遊戲過程全程以回合制進行，兩種模式有不同的結束方式，以下為兩種模式的結束條件。

遊戲模式	結束條件
闔家歡模式	每喝一次酒，就新增一回合，滿5 個回合後，遊戲結束並結算。
無乃酒鬼模式	當任一玩家累積喝滿 3 杯，遊戲立即結束。

Difficulties 遇到的困難

• 在電源開啟狀態下，不小心將電源供應器與 L298N 馬達驅動器疊放接觸，造成瞬間短路產生火花，導致連接線燒斷，好險設備未受損。
• 在測試硬體設備時，第三台幫浦無法運作，排查後發現是線路未銜接好，調整後恢復了運作。
• 規格未定義清楚，所以做出的功能有所落差。
• 前期階段，前端和後端分開進行製作，導致在串接出現各種 Bug ，後續經過了一連串的測試和重新製作，得以正常運行。

Vision for the future 未來展望

• 增強例外處理，如防止錯誤的人為操作。

• 彈性酒單設計，你的酒單你做主。

• 骰子小遊戲與規則豐富化，增加更多小遊戲。

  ✨🐧 happy ending ~！🍻🎉

Job Assignment 分工表

組員	學號	工作内容
張詠筑	112213065	主題發想、GPIO開發、硬體設計、遊戲規則設定
郭又榛	111241014	主題發想、後端、遊戲規則設定
吳雅惠	113108048	GPIO協助、簡報製作、外殼設計、遊戲規則設定
張廷伃	112213063	前端、簡報製作、撰寫 README 、遊戲規則設定
莊佩諺	112213068	前端、外殼設計、撰寫 README 、遊戲規則設定

Acknowledgments 感謝名單

• BlueT
• Reg 學長 https://github.com/bs10081
• Chat GPT
• Gemini
• Claude code
• 蓬萊人偶

酒支援

• Reg 學長
• BT(烈酒)
• @ume-latte https://github.com/ume-latte

客串名單

BlueT、蓬萊人偶、Josh學長、陳章銓(Jerry)、張峻碩、李玨叡(Jerry)

References

• https://www.youtube.com/watch?v=Ytjkh6xWdrY&t=212s
• https://atceiling.blogspot.com/2014/01/raspberry-pigpio.html
• https://hackmd.io/@ncnu-opensource/book/https%3A%2F%2Fhackmd.io%2F%40ncnu-opensource%2FSJfAeJSTle#Hello-World-%E7%AF%84%E4%BE%8B