---
# System prepended metadata

title: Function Format Document
tags: [Speaker]

---

---
title: Function Format Document
tags: Speaker
---
# Function Format Document
所有僅限音箱內使用的 function
~~因為系統架構的問題，所有的 function 需要有 return，這個 return value 對於大部分的功能來說應該會是要丟到文字轉~~
~~> For features that need to be called by 「文字理解」, please specify the variable needed to call your feature function.~~
### Requirements
1. Arguments type & name
2. 缺少某個 Arguments 的話，需要執行的動作（重新詢問使用者）
3. 簡單說明 function 作用
4. Descripition 可以中文
5. Arguments default value

### 命名格式
class: 首字母大寫駝峰式
function: 底線
variable: 駝峰
### return 格式
`(class_name, function_name, (arg...))`
class_name, function_name: 要呼叫的 class 和 function name，無則該欄為 None
(arg): 被呼叫的 function 所需參數，無則該欄為 None
## 文字理解

class:Extract
### Extract.main(input_str)
| Name | Arguments type | Default value | Description |
|:----:|:--------------:| :-------------: |:-----------:|
| input_str  |   **string**   | -             | 原始輸入  |

從語音辨識接收輸入字串，並回傳所要呼叫的 function 及其參數
<!-- 
### text2func(input_str)
|   Name    | Arguments type | Default value |         Description         |
|:---------:|:--------------:| :-------------: |:---------------------------:|
| input_str |   **string**   | -             | to see what user want to do |

從語音辨識接收輸入字串，回傳即將呼叫的 function名稱及對應到的關鍵字
### isPhoneNumber(str)
| Name | Arguments type | Default value | Description |
|:----:|:--------------:| :-------------: |:-----------:|
| str  |   **string**   | -             | the target  |

判斷字串是否為電話號碼（`r'\d(-\d)*'`）

### para_extract(input_str, func_key)
| Name | Arguments type | Default value | Description |
|:----:|:--------------:| :-------------: |:-----------:|
| input_str  |   **string**   | -             | 原始輸入  |
|func_key|**list**|-|[0]：即將呼叫的 function 名稱<br>[1]：對應到的關鍵字|

根據即將要呼叫的 function 從原始字串中提取參數

### _trans(input_str)

| Name | Arguments type | Default value | Description |
|:----:|:--------------:| :-------------: |:-----------:|
| input_str  |   **string**   | -             | the target  |

將 input_str 的數字字串轉為數字

### set_time(newtime)
| Name | Arguments type | Default value | Description |
|:----:|:--------------:| :-------------: |:-----------:|
| newtime  |   **list**   | -             | [year, month, hour, minute]  |

根據 newtime 所示回傳指定時間字串

### target_time(input_str, mode)
| Name | Arguments type | Default value | Description |
|:----:|:--------------:| :-------------: |:-----------:|
| input_str  |   **string**   | -             | the target  |
|mode|**int**|-|0 for calender related<br>1 for weather related|

根據輸入字串提取所想表達的時間及剩餘字串 -->

## 語音辨識
### SpeechToText.voice_to_text()
No parameter.
|   Name    | Arguments type | Default value |         Description         |
|:---------:|:--------------:| :-------------: |:---------------------------:|
| return |   **string**   | NULL | 語音辨識結果 |

## 文字轉語音
### TextToSpeech.text_to_voice(sentence)
|   Name    | Arguments type | Default value |         Description         |
|:---------:|:--------------:| :-------------: |:---------------------------:|
| sentence |   **string**   | NULL | 要轉成語音的句子 |

No return value.

## 即時翻譯功能
### Translate.translate(fromLanguage, toLanguage)
|   Name    | Arguments type | Default value |         Description         |
|:---------:|:--------------:| :-------------: |:---------------------------:|
| fromLanguage |   **string**   | 'zh-TW' | 原語言 |
| toLanguage |   **string**   | 'en'  | 新語言 |
* fromLanguage, toLanguage只支援'zh-TW'（中文）, 'en'（英文）, 'fr'（法文）

No return value.

## 天氣功能
class: Weather
### weather_forecast(time, place)
|   Name   | Arguments type | Default value |         Description         |
|:--------:|:--------------:|:-------------:|:---------------------------:|
| time | **datetime** | datetime.now() | 使用者想要查詢天氣預報的時間 |
|  place  |   **string**   | 使用者設定之位置 <br> or <br> 透過 IP 尋找音箱位置 | 使用者想要查詢天氣預報的地區 <br> (台灣縣市 or 全球都市) |

從文字理解接收使用者想要查詢的天氣預報之時間以及地點資訊(地點為台灣縣市或全球都市)，透過連結外部api查詢該地區該時間的天氣預報資訊，若查無此地點或是欲查詢的時間超過一週，則回傳「查詢不到」至文字轉語音

#### response
| Name           | Value      |
| -------------- | ---------- |
| situation      | **string** |

回傳天氣狀況

## 音樂功能
class: MusicStreaming
### play_music(target)
|   Name   | Arguments type | Default value |         Description         |
|:-----:|:--------------:|:--------------------------------------:|:----------------------------:|
| target  |  **string**  |     -     | 使用者欲播放音樂之關鍵字 <br> 歌名 or 歌手+歌名 |

從文字理解接收使用者想要播放的音樂關鍵字（歌名 or 歌手+歌名），透過連結外部api查詢該歌曲並播放

No return value.

### pause_music()
暫停現在正在播放的音樂

No return value.

### continue_music()
繼續播放已暫停的音樂

No return value.

### stop_music()
停止現在正在播放或暫停中的音樂

No return value.

### now_playing()
回傳現在正在播放的歌手以及歌曲名稱

#### response
| Name               | Value       |
| ------------------ | ----------- |
| nowMusic           | **string** |

### repeat_playing()
重複播放音樂

No return value.

### return_playing_status()
回傳現在音樂的狀態。
若音樂正在播放，全域變數isPlaying = T、isPause = F、isStop = F。
若音樂狀態是暫停中，全域變數isPause = T、isPlaying = F、isStop = F。
若音樂已停止，全域變數isStop = T、isPlaying = F、isPause = F。

#### response
| Name               | Value       |
| ------------------ | ----------- |
| isPlaying          | **Boolean** |
| isPause            | **Boolean** |
| isStop             | **Boolean** |

<!--
## 雙聲道功能
### close_dual_speaker()
取消雙聲道模式，並斷開兩音箱的藍芽
### connect_dual_speaker(speakerNickname)
|   Name   | Arguments type | Default value |         Description         |
|:-----:|:--------------:|:--------------------------------------:|:----------------------------:|
| speakerNickname  |  **string**  |     -     | 使用者的第要連接的音箱代稱 |
### play_music_dual_speaker(music)
|   Name   | Arguments type | Default value |         Description         |
|:-----:|:--------------:|:--------------------------------------:|:----------------------------:|
| music  |  **vlc instance**  |     -     | vlc(播放模組) 的 instance |
-->
## 藍芽音箱
### Bluetooth.open_bluetooth()
會開啟藍芽並可以被偵測
### Bluetooth.close_bluetooth()
斷開連接並關閉藍芽
### Bluetooth.get_bluetooth_status()
查詢藍牙連接狀態
#### response
| Name               | Value       |
| ------------------ | ----------- |
| isConnect          | **Boolean** |
| connectedDeviceMAC | **string**  |


### Bluetooth.pause_bluetooth_playing()
若有正在進行的音樂會傳送訊號到手機暫停


## 問題回答
### 
class: QuestionAnswering
@HsuanYu 抱歉，那個是class的名稱

從網路搜尋取得使用者問題查詢到的結果、答案，最後回傳可能的答案。
如果查詢不到合理的答案，將回傳「無相關搜尋結果」。
如果設定為將結果回傳給使用者，將呼叫相關 API 。

### google_search( query_str )
透過 Google 進行網路查詢。
|   Name    | Arguments type | Default value | Description      |
|  ------   | :------------: | ------------- |:----------------:|
| query_str |  **string**    |       -       |使用者欲查詢之問題字串|
| return    |  **list**      |       -       |  網頁搜尋結果      |

### get_answer( results )
將查到的結果頁面進行處理，取得想要的部分，輸出答案以及相關資料。
|   Name    | Arguments type | Default value | Description      |
|  ------   | :------------: | ------------- |:----------------:|
|  result   |    **list**    |       -       |    網頁搜尋結果    |
|  return   |   **string**   |       -       |答案字串/相關查詢結果|


## Calendar
class: Calendar
### add_calendar(date, start_time, end_time, event)
|   Name   | Arguments type | Default value |         Description         |
|:--------:|:--------------:|:-------------:|:---------------------------:|
| start_time  |   **string**   | - | 活動開始時間 |
| end_time  |   **string**   | start_time 後一小時 | 活動結束時間 |
| event  |   **string**   | - | 活動名稱 |

### add_calendar_week(day, start_time, end_time, event)
|   Name   | Arguments type | Default value |         Description         |
|:--------:|:--------------:|:-------------:|:---------------------------:|
| day | **unsigned int** | - | 重複週幾 |
| start_time  |   **string**   | - | 活動開始時間 |
| end_time  |   **string**   | start_time 後一小時 | 活動結束時間 |
| event  |   **string**   | - | 活動名稱 |

重複每週 day 直到當年年底


### add_calendar_day(start_time, end_time, event)
|   Name   | Arguments type | Default value |         Description         |
|:--------:|:--------------:|:-------------:|:---------------------------:|
| start_time  |   **string**   | - | 活動開始時間 |
| end_time  |   **string**   | start_time 後一小時 | 活動結束時間 |
| event  |   **string**   | - | 活動名稱 |

重複每天直到當年年底


### read_calendar(date)
|   Name   | Arguments type | Default value |         Description         |
|:--------:|:--------------:|:-------------:|:---------------------------:|
| date | **string** | date.today() | 活動日期 |

查詢於 date 開始且結束的行程

### read_calendar_next()
查詢下一個行程


## Make calls
class: Call
### make_call(number)
|   Name   | Arguments type | Default value |         Description         |
|:--------:|:--------------:|:-------------:|:---------------------------:|
| number | **string** | - | 使用者想要撥打的號碼 |


## 系統音量控制

### Volume.louder_system_volume(value)
| Name  | Arguments type | Default value | Description |
| ----- | -------------- | ------------- | ----------- |
| value | unsigned int            | 5             | 上升多少音量            |

### Volume.quieter_system_volume(value)
| Name  | Arguments type | Default value | Description |
| ----- | -------------- | ------------- | ----------- |
| value | unsigned int            | 5             | 下降多少音量            |

### Volume.set_system_volume(value)
| Name  | Arguments type | Default value | Description |
| ----- | -------------- | ------------- | ----------- |
| value | unsigned int   | 未修改前的值  | 音量設定值  |
    
### Volume.get_system_volume()
| Name   | Arguments type | Default value | Description      |
| ------ | -------------- | ------------- | ---------------- |
| return | unsigned int   | 當前值        | 回傳當前系統音量 |

## 音樂音量控制

### Volume.louder_music_volume(value)
| Name  | Arguments type | Default value | Description  |
| ----- | -------------- | ------------- | ------------ |
| value | unsigned int   | 5             | 上升多少音量 |

### Volume.quieter_music_volume(value)
| Name  | Arguments type | Default value | Description  |
| ----- | -------------- | ------------- | ------------ |
| value | unsigned int   | 5             | 下降多少音量 |

### Volume.set_music_volume(value)
| Name  | Arguments type | Default value | Description |
| ----- | -------------- | ------------- | ----------- |
| value | unsigned int   | 未修改前的值  | 音量設定值  |

### Volume.get_music_volume()
| Name   | Arguments type | Default value | Description      |
| ------ | -------------- | ------------- | ---------------- |
| return | unsigned int   | 當前值        | 回傳當前系統音量 |

## 傳輸搜尋結果至手機
### deliver_to_cellphone(resultURL,keyWord,userId)
class:Delivery
| Name   | Arguments type | Default value | Description      |
| ------ | -------------- | ------------- | ---------------- |
| resultURL |  string  |     -    | 問題回答找到的網址 |
| keyWord |  string  |     -    | 用來搜尋的關鍵字 |
| userId  |  string  |     ""    |    要傳過去的userId，因為伺服器不會知道是哪個使用者傳的，如果沒有綁定的話就傳空字串    |
| return  |  int  |     -    |    回傳傳輸結果    |

0：網頁與LINE皆傳送失敗、1：網頁傳送成功，LINE傳送失敗、2：網頁傳送失敗，LINE傳送成功、3：網頁與LINE皆傳送成功
## 使用音箱紀錄備忘錄
### memorandum()
class:Memorandum
| Name   | Arguments type | Default value | Description      |
| ------ | -------------- | ------------- | ---------------- |
| return  |    |     -    |  |

## 倒計時 

### Countdown.set_timer(hours, minute, second)
| Name   | Arguments type | Default value | Description  |
| ------ | -------------- | ------------- | ------------ |
| hours  | int            |               |              |
| minute | int            |               |              |
| second | int            |               |              |
| return | boolean        |               | 輸入是否合法 |


## 世界時鐘
### WorldTime.get_time_at_place(place)
class: WorldTime
| Name   | Arguments type | Default value | Description |
| ------ | -------------- | ------------- | ----------- |
| place  | string         | 使用者所在地  |             |
| return | string         | XX:XX(24小時制)              |             |


## 鬧鐘
### Alarm.set_alarm(day, hour, minute)
class: Alarm
| Name   | Arguments type | Default value | Description |
| ------ | -------------- | ------------- | ----------- |
| day  | int(1-7)            | 今天或明天（最近抵達時間）              |             |
| hours  | int            |             |             |
| minute | int            |             |             |
| return | None           |               |             |

## 重置
### listen_reset_button()
class: FactoryReset
Should be a daemon thread
No return value

### factory_reset()
class: FactoryReset
This function can only be accessed via GPIO input
No return value