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()，就可以知道你的机器人上有哪些可用的姿势族。它一定是下面这个列表的子集。

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)：

当姿势发生改变时，传递出姿势的名称。
这个事件的更新频率大约是一秒钟。