Package: emo-platform-api-sdk
BOCCO emo platform api python sdkLibrary DocumentationHow to installUsing poetry (if you want to use in python virtual environment)If poetry has not been installed, please seethis pageto install.gitclonehttps://github.com/YUKAI/emo-platform-api-python.gitcdemo-platform-api-python# Python 3.7+ requiredpoetryinstall--no-devWhen you execute python code,poetryrunpythonyour_python_code.pyUsing PyPl# Python 3.7+ required
$ pip3 install emo-platform-api-sdkSetting api tokensYou can see access token & refresh token from dashboard inthis pageafter login.Then, set those tokens as environment variables in terminal.exportEMO_PLATFORM_API_ACCESS_TOKEN="***"exportEMO_PLATFORM_API_REFRESH_TOKEN="***"Or, you can give as argument when initializing client in python code.fromemo_platformimportClient,Tokensclient=Client(tokens=Tokens(access_token="***",refresh_token="***"))NoteOnce you set tokens as arguments or environment variables, the tokens are saved in the sdk and you don't need to specify any arguments or set any environment variables next time.If you want to overwrite the tokens with the other tokens, for example if you want to change your account, set the new tokens again with arguments or environment variables.Usage ExampleYou can also see other examples in "examples" directory.NoteWhen you initialize emo_platform.Client, without the argumentuse_cached_credentialsgiven asTrue, two json files (emo-platform-api.json & emo-platform-api_previous.json) are created in the path where emo_platform module was installed.These files are used to store the tokens information.See the documentation for details.You can change the path where these json files are created, as shown below.importosfromemo_platformimportClientCURRENT_DIR=os.path.abspath(os.path.dirname(__file__))client=Client(token_file_path=CURRENT_DIR)Example1 : Using clientfromemo_platformimportClient,Headclient=Client()print(client.get_account_info())print(client.get_stamps_list())room_id_list=client.get_rooms_id()room_client=client.create_room_client(room_id_list[0])print(room_client.get_msgs())room_client.move_to(Head(10,10))For business userWhen you use business version, you need to give api_key as argument for some functions.You can find the API key inthis pageafter login with business account.fromemo_platformimportBizBasicClient,BizAdvancedClient# business basic versionclient=BizBasicClient()# business advanced versionclient=BizAdvancedClient()print(client.get_account_info())print(client.get_stamps_list(api_key))room_id_list=client.get_rooms_id(api_key)# give api_key to room clientroom_client=client.create_room_client(api_key,room_id_list[0])# need not to give api_key to room client method# if you want to change api_key, please create another room_client for each api_keyprint(room_client.get_msgs())Example2 : Receive webhookIn another terminal, execute ngrok and copy URL forwarded tohttp://localhost:8000.ngrokhttp8000Case1 : Using functionstart_webhook_event()(Recommended)You can use the decoratorevent()to register functions as callback functions.And, you can get the corresponding callback function and the parsed body by giving the webhook request body as the argument of the functionget_cb_func().Please check if theX-Platform-Api-Secretin the header of the webhook request is the same as the return value ofstart_webhook_event()to avoid unexpected requests from third parties.importjson,http.serverfromemo_platformimportClient,WebHook,EmoPlatformErrorclient=Client()# Please replace "YOUR WEBHOOK URL" with the URL forwarded to http://localhost:8000client.create_webhook_setting(WebHook("YOUR WEBHOOK URL"))@client.event('message.received')defmessage_callback(data):print("message received")print(data)@client.event('illuminance.changed')defilluminance_callback(data):print("illuminance changed")print(data)secret_key=client.start_webhook_event()# localserverclassHandler(http.server.BaseHTTPRequestHandler):def_send_status(self,status):self.send_response(status)self.send_header('Content-type','text/plain; charset=utf-8')self.end_headers()defdo_POST(self):# check secret_keyifnotsecret_key==self.headers["X-Platform-Api-Secret"]:self._send_status(401)returncontent_len=int(self.headers['content-length'])request_body=json.loads(self.rfile.read(content_len).decode('utf-8'))try:cb_func,emo_webhook_body=client.get_cb_func(request_body)exceptEmoPlatformError:self._send_status(501)returncb_func(emo_webhook_body)self._send_status(200)withhttp.server.HTTPServer(('',8000),Handler)ashttpd:httpd.serve_forever()Case2 : Using functionregister_webhook_event()(Not recommended)You can't use the decoratorevent()to register functions as callback functions.So, you need to call the callback functions yourself after webhook request body is parsed usingparse_webhook_body().Please check if theX-Platform-Api-Secretin the header of the webhook request is correct using the return value ofregister_webhook_event()to avoid unexpected requests from third parties.importjson,http.serverfromemo_platformimportClient,WebHook,parse_webhook_bodyclient=Client()# Please replace "YOUR WEBHOOK URL" with the URL forwarded to http://localhost:8000client.create_webhook_setting(WebHook("YOUR WEBHOOK URL"))defmessage_callback(data):print("message received")print(data)defilluminance_callback(data):print("illuminance changed")print(data)response=client.register_webhook_event(['message.received','illuminance.changed'])secret_key=response.secret# localserverclassHandler(http.server.BaseHTTPRequestHandler):def_send_status(self,status):self.send_response(status)self.send_header('Content-type','text/plain; charset=utf-8')self.end_headers()defdo_POST(self):# check secret_keyifnotsecret_key==self.headers["X-Platform-Api-Secret"]:self._send_status(401)returncontent_len=int(self.headers['content-length'])request_body=json.loads(self.rfile.read(content_len).decode('utf-8'))emo_webhook_body=parse_webhook_body(request_body)ifemo_webhook_body.event=="message.received":message_callback(emo_webhook_body)elifemo_webhook_body.event=="illuminance.changed":illuminance_callback(emo_webhook_body)else:passself._send_status(200)withhttp.server.HTTPServer(('',8000),Handler)ashttpd:httpd.serve_forever()Cli ToolYou can use the commandemo_platform_cliafter installing this package.Example1 : Use clientInitially, you need to specify your account refresh token.$emo_platform_clipersonal--refresh_token***get_account_infoOnce you set refresh_token, you don't need to set again.$emo_platform_clipersonalget_account_infoExample2 : Use room clientPlease replaceROOM_IDwith room id which you want to use.$ emo_platform_cli personal create_room_client ROOM_ID change_led_color 10 10 200You can get room id as shown below.$ emo_platform_cli personal get_rooms_idOr, you can use "room" command which does not require the room id to be specified.
This is because it callsget_rooms_id()internally and specifies the first room id.$ emo_platform_cli personal room change_led_color 10 10 200HelpIf you run a command without giving any arguments, a list of available commands(functions) or required arguments will be displayed with explanations.Example1 : Show available clients$emo_platform_cli

NAMEemo_platform_cli

SYNOPSISemo_platform_cliCOMMAND

COMMANDSCOMMANDisoneofthefollowing:biz_advanced各種apiを呼び出す同期版のclient(BusinessAdvanced版)biz_basic各種apiを呼び出す同期版のclient(BusinessBasic版)personal各種apiを呼び出す同期版のclient(Personal版)Example2 : Show available functions in personal version$emo_platform_clipersonal
NAMEemo_platform_clipersonal

SYNOPSISemo_platform_clipersonal-COMMAND

COMMANDSCOMMANDisoneofthefollowing:change_webhook_settingWebhookの設定の変更create_room_client部屋固有の各種apiを呼び出すclientの作成create_webhook_settingWebhookの設定の作成delete_account_infoアカウントの削除

:...Example3 : Show available functions unique to room in personal version$emo_platform_clipersonalroom
NAMEemo_platform_clipersonalroom

SYNOPSISemo_platform_clipersonalroomCOMMAND|VALUE

COMMANDSCOMMANDisoneofthefollowing:change_led_colorほっぺたの色の変更get_emo_settings現在のBOCCOemoの設定値を取得get_msgs部屋に投稿されたメッセージの取得get_sensor_values部屋センサの送信値を取得

:...Example4 : Show the required argument ofchange_webhook_setting()$emo_platform_clipersonalchange_webhook_setting
ERROR:Thefunctionreceivednovaluefortherequiredargument:url
Usage:emo_platform_clipersonalchange_webhook_settingURL<flags>optionalflags:--description

Fordetailedinformationonthiscommand,run:emo_platform_clipersonalchange_webhook_setting--help