❌ ❌ ✅ ✅ ✅ ✅

Xbox コントローラー

../_images/xboxcontroller.png
controller
class XboxController(joystick_deadzone=10, name=None, timeout=10000, connect=True)

リモート制御のためのセンサーとして Microsoft® Xbox® コントローラーを使います。

ハブはコントローラーをスキャンして接続します。プログラムが終了すると切断します。

接続性とペアリングのヒントについては 後述 します。

パラメータ:

  • joystick_deadzone (Number, %) -- ジョイスティックのデッドゾーン(0～100)。両軸ともこのしきい値以下の値は、スティックドリフトを防ぐために0として報告されます。

  • name (str) -- 接続する Xbox コントローラーの Bluetooth 名。利用可能なコントローラーに接続する場合は None を指定します。

  • timeout (Number, ms) -- 接続が確立するまでの待ち時間。無期限に待つ場合は None を指定します。

  • connect (bool) -- コントローラーへの接続をスキップするには False を選択してください。後で connect() を呼び出すことで接続できます。

awaitconnect()

Xbox コントローラーに接続します。コントローラーを切断した場合、または connect=False で初期化した場合にのみ必要です。

awaitdisconnect()

Xbox コントローラーの接続を解除します。

name() → str

接続されているコントローラーの Bluetooth 名を取得します。

戻り値:

コントローラーの Bluetooth 名。

例外:

OSError -- コントローラーが接続されていない場合に発生します。

controllerAis pressed
buttons.pressed() → Set[Button]

現在押されているボタンをチェックします。

戻り値:

押されているボタンのセット。

ボタンには次のものがあります:

  • Button.A, Button.B, Button.X, Button.Y

  • Button.UP, Button.DOWN, Button.LEFT, Button.RIGHT (方向パッド)。これらのうち最大で2つまで同時に押せます。

  • Button.LB and Button.RB (バンパー)

  • Button.LJ and Button.RJ (ジョイスティックの押下)

  • Button.VIEW, Button.MENU, Button.GUIDE (the Xbox logo), Button.UPLOAD

  • Button.P1, Button.P2, Button.P3, Button.P4 (Elite シリーズ 2 のみ) パドルの押下は、現在アクティブなプロファイルによっては他のボタンの押下として検出される場合があります。

controllerleft joystick horizontal
controllerleft joystick vertical
joystick_left() → Tuple

左のジョイスティックの位置を、-100% から 100% の割合で取得します。中心位置は (0, 0) です。正方形のデッドゾーンが適用されます。両方の軸がデッドゾーン内にある場合、両方とも0として報告されます。

戻り値:

X (水平方向)および Y (垂直方向)位置のタプル。

例外:

OSError -- コントローラーが接続されていない場合に発生します。

controllerright joystick horizontal
controllerright joystick vertical
joystick_right() → Tuple

右のジョイスティックの位置を、-100% から 100% の割合で取得します。中心位置は (0, 0) です。正方形のデッドゾーンが適用されます。両方の軸がデッドゾーン内にある場合、両方とも0として報告されます。

戻り値:

X (水平方向)および Y (垂直方向)位置のタプル。

例外:

OSError -- コントローラーが接続されていない場合に発生します。

controllerleft trigger
controllerright trigger
triggers() → Tuple

左右のトリガーの位置を、0% から 100% の割合で取得します。

戻り値:

左右のトリガー位置のタプル。

例外:

OSError -- コントローラーが接続されていない場合に発生します。

controllerdirection pad
dpad() → int

方向パッドの値を取得します。 1 は上、 2 は右上、 3 は右、 4 は右下、 5 は下、 6 は左下、 7 は左、 8 は左上押されていることを示します。 0 は押されていないことを示します。

これは基本的に Button.UP, Button.RIGHT, Button.DOWN, Button.LEFT ボタンの状態を読み取るのと同じですが、このメソッドでは利便性を考慮して方向を示す数値を返します。

戻り値:

方向パッドの押した方向を示す値。

例外:

OSError -- コントローラーが接続されていない場合に発生します。

controllerprofile
profile() → int

コントローラーの現在のプロファイルを取得します。Xbox Elite コントローラー シリーズ 2 でのみ利用可能です。

戻り値:

プロファイル番号。

例外:

OSError -- コントローラーが接続されていない場合に発生します。

controller100%200msrumble atfor
controller5001000list with200msrumble atfor
controller100%200msrumble atfor1times with pause100ms
awaitrumble(power=100, duration=200, count=1, delay=100)

内蔵アクチュエーターを振動させ、フォースフィードバックを起こします。

単一の power 値を指定すると、そのパワーで左右のメインアクチュエータが両方とも振動しますが、トリガーアクチュエータはオフのままです。よりきめ細かな制御を行うには、パワーを4つの値のタプルとして設定します。これらの値は、それぞれ左メインアクチュエータ、右メインアクチュエータ、左トリガーアクチュエータ、右トリガーアクチュエータを制御します。たとえば power=(0, 0, 100, 0) とすると、左トリガーが最大パワーで振動します。

振動はプログラムが実行される間にバックグラウンドで実行されます。プログラムを待機させるには、対応する期間だけプログラムを一時停止します。1つの振動の場合、これは duration と等しいです。複数の振動の場合、これは count * (duration + delay) と等しいです。

このメソッドは、アクチュエータのすべてのパワーがゼロの場合、 duration がゼロの場合、 count が1未満の場合には何も行いません。

パラメータ:

  • power (Number, % or tuple) -- 振動パワー。単一の値は両方のメインアクチュエータに適用されます(0～100%)。タプルは個別に(左ハンドル、右ハンドル、左トリガー、右トリガー)に適用されます。

  • duration (Number, ms) -- 各振動の持続時間。最大2500ミリ秒。

  • count (int) -- 振動の回数(0～100)

  • delay (Number, ms) -- 各振動の前に遅延時間を設けます。 count > 1 である場合のみ適用します。最大遅延時間は2500ミリ秒です。

Xbox コントローラーのペアリング手順

コントローラーをハブに初めて繋げる場合、それらをペアリングする必要があります。コントローラーの電源を入れ、次にコントローラーの背面にあるペアリングボタンを数秒間押し続けます。押し続けるのを止めると、Xbox ボタンがより速く点滅し始めます。その後、プログラムを起動します。

ペアリングが成功し、接続が確立されると、Xbox ボタンの点滅が停止し、プログラムが実行されている間は点灯し続けます。

再接続

同じコントローラーを同じハブで使用し続ける場合、次回以降は単にコントローラーの電源を入れるだけで、このクラスを使ったプログラムの実行時に、ハブが自動的にコントローラーに接続します。

Xbox コントローラーが、この簡略化した接続を受け付けるのは、最後に接続したデバイスのみです。したがって、Xbox ゲーム機本体に接続するよう戻したり、別のハブに接続する場合は、前述の手順に従って再度ペアリングする必要があります。

利用できるコントローラー

2016年以降にリリースされたすべての Xbox コントローラーが利用できます。これには、One S のコントローラー (2016年の 1708)、Elite Series 2 (2019年の 1797)、執筆時点で最新のモデル Series X/S (2020年の 1914)が含まれます。

各コントローラーのモデル番号と画像については この概要 も参照してください。

Xbox コントローラーの更新

Xbox コントローラーを頻繁にゲーム機本体に繋いで使っている場合、おそらくコントローラーはすでに最新の状態になっているでしょう。一時的に使っていなかった場合や最近購入した場合は更新が必要な場合があります。

ゲーム機本体を使わずにコントローラーを更新するには Windows コンピューターで Xbox Accessories アプリを使います。これは Microsoft Store からダウンロードできます。コントローラーを USB 経由でコンピューターに接続し、アプリ内の "Update now" をクリックする指示にしたがってください。

テクニックハブの制限

テクニックハブの制限により、Xbox コントローラーを検索する際にハブがコンピューターから切断されます。これは、 print 命令からの出力を見れなくなることを意味します。また、プログラムを変更したい場合は、再びコンピューターに接続する必要があります。