NAO機器人學習小計

NAO APIs

nao的接口所有以AL開頭，所有繼承自ALModule,它被包含在<alcommon/almodule.h>中。
下面是ALModule的主要methods。

ALModule APIs

namespace : AL

#include <alcommon/almodule.h>

任務調度

ALModule::isRunning()

bool ALModule::isRunning(const int& id);

肯定被一個‘post’建立的方法是否還在運行。(注：post可能相似於一個線程池管理員，方法的編號可能相似於線程號)。

params: id - 被post所返回的函數的編號
return: true表示該方法正在被執行，false表示該方法沒有被執行。

---

ALModule::wait()

bool ALModule::wait(const int& id, const int& timeour);

等待編號爲id的方法執行完畢。

params: id - 被post所返回的函數的編號
        timeout - ms爲單位，表示
return: true表示該方法正在被執行，false表示該方法沒有被執行。

---

ALModule::stop()

void ALModule::stop(const int& id);

根據id中止相應方法。比較提倡模塊開發人員實現這個接口，當模塊內包含長時間執行的方法，而又但願容許用戶打斷。

params: id - 被post返回的方法的編號
return:

---

ALModule::exit()

void ALModule::exit();

將這個模塊從父經紀人(parent broker)中註銷。一旦這個方法被調用，這個模塊將再也不可用。開發人員應該在但願執行完全的關機任務時重寫這個方法。


——warning:
不建議在覈心模塊（例如 ALMemory 或者 ALMotion）中存在別的模塊或者方法正在調用它們時使用。

---

Bound Methods - Introspection
(↑不太理解，字面翻譯是：綁定的方法-反思)

ALModule::getBrokerName()

std::string ALModule::getBrokerName();

獲取父經紀人的名稱

return: 父經紀人的名稱。

---

ALModule::getMethodList()

std::vectore<std::string> ALModule::getMethodList();

獲取當前模塊的方法名稱列表。

return: 包含方法名稱的向量。

---

ALModule::getMethodHelp()

AL::ALValue ALModule::getMethodHelp(const std::string& methodName);

獲取一個方法的描述文檔。

params: methodName - 方法的名稱
return: 一個包含了方法的描述內容的結構體

注：
AL::ALValue [
    std::string methodName, 
    [ parameter, ... ]
    std::string returnName,
    std::string returnDescription
]

parameter:
[
    std::string parameterName,
    std::string parameterDescription
]

---

ALModule::getModuleHelp()

AL::ALValue ALModule::getModuleHelp();

獲取當前模塊的描述。

return: 一個包含模塊描述的結構體。

注：
AL::ALValue
[
    std::string moduleDescription,
    [ moduleExample, ... ]
]

moduleExample:
[
    std::string language,
    std::string example
]

---

ALModule::getUsage()

std::string ALModule::stop(const std::string& methodName);

根據函數名稱返回該函數的用法。

params: methodName - 函數名稱。
return: 總結了該函數用法的字符串。

---

ALModule::ping()

bool ALModule::ping();

單純爲了測試鏈接的ping。永遠返回true

return: true

---

ALModule::version()

std::string ALModule::version();

返回模塊的版本

return: 模塊的版本信息字符串。

以上接口將做爲公共接口存在於全部模塊中。

因爲咱們的項目以通訊爲主，所以咱們優先關注通訊模塊ALConnectionManagerProxy。

概覽：
ALConnectionManager提供管理網絡鏈接的方法。它包含了一些容許你鏈接或配置一個網絡的命令，而且也能夠獲取網絡的屬性或者建立一個網絡。
ALConnectionManager支持的網絡包括：以太網、無線網和藍牙。
主要的特性包括：

• 列舉出全部可用的網路服務。

• 鏈接到一個網絡服務。

• 建立一個網絡服務（包括WiFi熱點以及藍牙我的局域網(Bluetooth PAN)）。

• 列舉可用的網絡技術（WiFi、藍牙、以太網）。

• 對一個網絡服務進行配置。

這個模塊提供網絡服務的一些有用的信息，好比WiFi鏈接的強度、如今的狀態、以及安全要求。

這個模塊經過事件機制來通知網絡的變化。

性能和約束：

• ALConnectionManager只在機器人端可用。

• 暫時不支持WPA安全加密。

• 搜索可用wifi熱點的功能在熱點模式下不可用。

• ALConnectionManager不處理藍牙設備的配對過程。

ALConnectionManager APIs

namespace : AL

#include <alproxies/alconnectionmanagerproxy.h>

鏈接管理模塊繼承自ALModule API。它也有自有的下列方法：

ALConnectionManagerProxy::state()
ALConnectionManagerProxy::services()
ALConnectionManagerProxy::technologies()
ALConnectionManagerProxy::service()
ALConnectionManagerProxy::connect()
ALConnectionManagerProxy::disconnect()
ALConnectionManagerProxy::forget()
ALConnectionManagerProxy::setServiceConfiguration()
ALConnectionManagerProxy::setServiceInput()
ALConnectionManagerProxy::scan()
ALConnectionManagerProxy::enableTethering()
ALConnectionManagerProxy::disableTethering()
ALConnectionManagerProxy::getTetheringEnable()
ALConnectionManagerProxy::tetheringName()
ALConnectionManagerProxy::tetheringPassphrase()
ALConnectionManagerProxy::countries()
ALConnectionManagerProxy::country()
ALConnectionManagerProxy::setCountry()
ALConnectionManagerProxy::interfaces()

---

ALConnectionManagerProxy::state()

std::string ALConnectionManagerProxy::state();

返回網絡鏈接的狀態（全局）。可能的值包括：
· "online" - 當有互聯網鏈接可用時。
· "ready" - 至少有一個設備被成功地鏈接
· "offline" - 目前沒有設備鏈接到nao

return: 全局的鏈接管理器狀態。

示例代碼：

#python 2.7
 
from naoqi import ALProxy

NAO_IP = "127.0.0.1"

alConnectionManager = ALProxy("ALConnectionManager", NAO_IP, 9559)

print "network state: " + alConnectionManager.state()

---

ALConnectionManagerProxy::scan()

std::string ALConnectionManagerProxy::state();

搜索臨近的網絡服務（包括全部可用的網絡技術）。可用服務的列表會被刷新，並在稍後被顯示，這頗有用。

---

ALConnectionManagerProxy::services()

AL::ALValue ALConnectionManagerProxy::services();

返回包含全部可用網絡服務的名稱以及屬性的列表。在此以前調用`ALConnectionManagerProxy::scan()`會更有用。

return: 一個ALValueNetworkInfo的數組。

示例代碼：

#列出全部可用的網絡服務

#coding=utf-8

from naoqi       import ALProxy

NAO_IP = "127.0.0.1"

alconnman = ALProxy("ALConnectionManager", NAO_IP, 9559)

#Scanning is required to update the services list
alconnman.scan()
services = alconnman.services()

for service in services:
    network = dict(service)
    if network["Name"] == "":
        print "{hidden} " + network["ServiceId"]
    else:
        print network["Name"] + " " + network["ServiceId"]

---

ALConnectionManagerProxy::service()

AL::ALValue ALConnectionManagerProxy::service(const std::string& serviceId);

返回一個指定的服務名稱的服務的網絡屬性。網絡信息NetworkInfo經過ALValue來表示。

params: serviceId - 但願得到屬性的網絡服務名稱
return: 指定的服務名稱網絡的屬性。
throws: 該網絡服務不可用時，拋出ALError

示例代碼：

#得到一個網絡服務的屬性
#coding=utf-8
from naoqi import ALProxy
import sys

NAO_IP = "127.0.0.1"

if len(sys.argv) != 2:
    print sys.argv[0] + " <serviceId>"
    sys.exit(1)

alconnman = ALProxy("ALConnectionManager", NAO_IP, 9559)

try:
  service = alconnman.service(sys.argv[1])
except Exception as e:
    print e.what()
    sys.exit(1)

service = dict(service)
print "Network Service: " + sys.argv[1]
for key, value in service.iteritems():
    print "\t" + key + ": " + str(value)

---

ALConnectionManagerProxy::connect()

void ALConnectionManagerProxy::connect(const std::string& serviceId);

鏈接到一個網絡服務。

params: serviceId - 將要鏈接到的網絡的名稱
throws: 該網絡服務不可用時，拋出ALError

注意：

若是在鏈接到這個網絡時須要別的信息（好比須要登陸密碼，或者登陸隱藏網絡須要網絡名稱時），將會產生一個event。

See also

NetworkServiceInputRequired(), NetworkConnectStatus()

示例代碼：

#鏈接到一個網絡
from naoqi import ALProxy
import sys

NAO_IP = "127.0.0.1"

if len(sys.argv) != 2:
    print sys.argv[0] + " <serviceId>"
    sys.exit(1)

alconnman = ALProxy("ALConnectionManager", NAO_IP, 9559)

try:
    alconnman.connect(sys.argv[1])
except Exception as e:
    print e.what()
    sys.exit(1)

---

ALConnectionManagerProxy::disconnect()

void ALConnectionManagerProxy::disconnect(const std::string& serviceId);

斷開到一個網絡服務的鏈接。

params: serviceId - 將要斷開的網絡的名稱
throws: 該網絡服務不可用時，拋出ALError

示例代碼：

#斷開一個網絡鏈接
from naoqi import ALProxy
import sys

NAO_IP = "127.0.0.1"

if len(sys.argv) != 2:
    print sys.argv[0] + " <serviceId>"
    sys.exit(1)

alconnman = ALProxy("ALConnectionManager", NAO_IP, 9559)

try:
  alconnman.disconnect(sys.argv[1])
except Exception as e:
    print e.what()
    sys.exit(1)

ALConnectionManagerProxy::disconnect()

void ALConnectionManagerProxy::forget(const std::string& serviceId);

忘記一個偏好網絡。須要得到網絡服務的名稱來忘記相關聯的信息。這還會使得這個網絡再也不是偏好網絡，而且不會被自動鏈接。

params: serviceId - 將要忘記的網絡的名稱
throws: 該網絡服務不可用時，拋出ALError

示例代碼：

#忘記一個網絡
from naoqi import ALProxy
import sys

NAO_IP = "127.0.0.1"

if len(sys.argv) != 2:
    print sys.argv[0] + " <serviceId>"
    sys.exit(1)

alconnman = ALProxy("ALConnectionManager", NAO_IP, 9559)

try:
  service = alconnman.forget(sys.argv[1])
except Exception as e:
    print e.what()
    sys.exit(1)

---

ALConnectionManagerProxy::setServiceConfiguration()

void ALConnectionManagerProxy::setServiceConfiguration(const AL::ALValue& configuration)

給定須要應用的靜態網絡配置。如下屬性在靜態配置中是可用的：
· 是否自動鏈接
· 域名
· 域名服務器
· IPv4
· IPv6（實驗性的）

params: configuration - 一個將要被應用網絡配置的包含了NetWorkInfo的ALValue。
throws: 當網絡服務不可用的時候拋出ALError
        當配置信息不合法時拋出ALError
        當網絡服務不須要配置時拋出ALError

See also
NetworkInfo

(未完)

ALRobotPosture模塊

概覽

暫時如今看看motion部分的模塊。ALRobotPosture模塊容許用戶將機器人定位到已經定義好的姿式。
能夠選擇使用ALRobotPostureProxy::goToPosture()或者ALRobotPosture::applyPosture.

• 若是想要建立一個自動化的應用，務必選擇ALRobotPostureProxy::goToPosture().

• 若是你僅僅但願在操控機器人時，迅速達到某個姿式，能夠選擇ALRobotPostureProxy::applyPosture，（你必需要協助機器人）。

這如何工做？

機器人會偵測到如今它正處於那種姿式，而後計算出一個路徑，使得它能夠從如今的姿式變換到目標姿式，而後執行這條線路。

可能容許選擇姿式變換的速度。

定義

姿式

機器人的姿式是一個獨特的，對他的關節和慣性傳感器的配置。
因爲姿式是由一組實數（好比說float）定義的，因此會有無數種姿式。

預約義的姿式

下面是預約義的姿式列表：

• 蹲伏(Crouch)

• 仰面躺(LyingBack)

• 面向下趴着(LyingBelly)

• 正坐(Sit)

• 箕踞(SitRelax)

• 站立(Stand)

• 預行走站立(StandInit)

• 向前看齊(StandZero)

有一些姿式（好比Sit或Lying）並非對全部機器人都是可用的。

使用ALRobotPostureProxy::getPostureList()來獲取你的機器人上可用的預約義的姿式列表。

姿式族

因爲姿式的種類有無數種，姿式被劃分爲姿式族，以是的姿式更加容易理解。
如下是姿式族列表:

使用ALRobotPostureProxy::getPostureFamilyList()，就能夠知道你的機器人上有哪些可用的姿式族。它必定是下面這個列表的子集。

Posture Family	Description
Standing	機器人的中心在腳上，而且機器人的軀幹是筆直向上的的。
Sitting	機器人的尾部接觸地面，而且軀幹是筆直向上的。
SittingOnChair	機器人的尾部接觸一個高約10cm的椅子，而且軀幹是筆直向上的。
LyingBelly	身體平展，而且面向下
LyingBack	身體平展，而且面向上
LyingLeft	身體平展，而且面向右側
LyingRight	身體平展，而且面向左側
Belly	面向下而且軀幹懸空
Back	面向後而且軀幹懸空
Left	膝蓋跪向左側，而且手部着地
Right	膝蓋跪向右側，而且手部着地

namespace:AL

方法列表

和別的模塊同樣，這個模塊繼承自ALModule API。它也有自有的下列方法。

class ALRobotPostureProxy：

• ALRobotPostureProxy::getPostureList()

• ALRobotPostureProxy::getPosture()

• ALRobotPostureProxy::goToPosture()

• ALRobotPostureProxy::applyPosture()

• ALRobotPostureProxy::stopMove()

• ALRobotPostureProxy::getPostureFamily()

• ALRobotPostureProxy::getPostureFamilyList()

• ALRobotPostureProxy::setMaxTryNumber()

事件

• PostureFamilyChanged()

• PostureChanged()

方法

ALRobotPostureProxy::getPostureList()

std::vector<std::string> ALRobotPostureProxy::getPostureList();

返回一個包含全部已經定義姿式的列表。

return: 包含全部已定義姿式的向量

---

ALRobotPostureProxy::getPosture()

std::string ALRobotPostureProxy::getPosture()

返回如今的**預約義姿式**名稱。若是如今的姿式不是預約義姿式，就會返回"Unknown".
return: 一個包含如今姿式的名稱的字符串。

ALRobotPostureProxy::goToPoture()

bool ALRobotPostureProxy::gotoPosture(const std::string postureName, const float speed);

讓機器人變換到預約義的姿式。速度多是能夠調節的。這個變化是「智能的」，它會從如今已有的開始姿式，自動選擇每一步，以變換到目標姿式。
這是一個會阻塞的函數調用。若是但願它不會阻塞線程，使用post。
params: postureName - 預約義的姿式名稱字符串。
        speed - 相對速度，範圍從0.0 - 1.0
return: 一個布爾值，代表目標姿式是否正確達到。

---

ALRobotPostureProxy::applyPosture()

bool ALRobotPostureProxy::applyPosture(const std::string& postureName, const float& speed);

將全部的預約義姿式中提到的關節設置到定義中的狀態。
在操控機器人時，使用這個方法以達到顯示出動做的效果。請將他想象成一條姿式變換的捷徑，假設這是你想要快速達到某一個姿式。機器人可能須要使用者的幫助以達到這個姿式。
這個方法的效果是當即的，而且其中沒有隻能因素在裏面。因此在設置姿式時，請當心。比方說，若是機器人如今正坐着，你調用了applyPosture("StandInit", 1.0)。這對於機器人多是很是危險的，若是你不幫助機器人站起來的話，它就會跌倒。
若是你想要機器人獨立地站起來，調用goToPosture().
這是一個會阻塞的函數調用。若是但願它不會阻塞線程，使用post。

params: postureName - 預約義的姿式名稱字符串。
        speed - 相對速度，範圍從0.0 - 1.0
return: 一個布爾值，代表目標姿式是否正確達到。

---

ALRobotPostureProxy::stopMove()

void ALRobotPostureProxy::stopMove();

中止當前的姿式插補動做。

---

ALRobotPostureProxy::getPostureFamily()

std::string ALRobotPostureProxy::getPostureFamily();

返回姿式族。

return: 返回當前的姿式族名稱。

---

ALRobotPostureProxy::getPostureFamilyList()

std::vector<std::string> ALRobotPostureProxy::getPostureFamilyList();

返回一個包含了全部預約義的姿式族名稱的向量。

return: 一個包含了全部預約義姿式族名稱的vector.

---

ALRobotPostureProxy::setMaxTryNumber(const int& maxTryNumber)

void ALRobotPostureProxy::setMaxTryNumber(const int& maxTryNumber);

設置當調用`ALRobotPostureProxy::goToPosture()`返回失敗以前，最大的嘗試次數。

params: maxTryNumber - 嘗試的次數，默認值是3.

Event: "PostureFamilyChanged"

callback(std::string eventName, std::string PostureFamily, std::string subscriberIdentifier);

當姿式族發生改變時，傳遞出姿式族的名稱。
這個事件的更新頻率大約是一秒鐘。

---

Event: "PostureChanged"

callback(std::string eventName, std::string Posture, std::string subscriberIdentifier)：

當姿式發生改變時，傳遞出姿式的名稱。
這個事件的更新頻率大約是一秒鐘。