Тренажёр подачи мяча
Интерфейс для производителей тренажёров подачи — пушек и роботов. Тренажёр сообщает корту о каждом поданном мяче, корт возвращает измеренный результат: где мяч приземлился, отбил ли его игрок и попал ли ответ в мишень.
Что это даёт
Тренажёр знает о мяче всё до вылета: когда подан, с какой скоростью и вращением, куда целились. Корт знает, что было после. Интерфейс соединяет две половины.
- Производитель получает то, чего у тренажёра нет, — результат каждого мяча рядом с параметрами подачи.
- Игрок получает тренировку с оценкой: мишени на схеме корта, голос «попал» или «мимо», серия подряд, итог в личном кабинете.
- Клуб получает услугу «тренажёр + корт с оценкой» вместо корзины мячей.
На экране корта такая тренировка выглядит как обычная тренировка «Пушка»: ничего нового игроку осваивать не надо.
Как подключиться
- Клуб выдаёт ключ тренажёра. Ключ передаётся в каждом запросе в заголовке
X-Integration-Key. - Ключ тренажёра открывает только методы этой страницы. Видео, счёт матчей, данные игроков и настройки корта по нему недоступны. Ключ системы клуба из локального API эти методы не открывает — ключи разные.
- Сервер корта сам соединений не открывает: тренажёр, его приложение или облако производителя спрашивает — корт отвечает. Для событий есть запрос с ожиданием.
| Откуда | Адрес | Кому подходит |
|---|---|---|
| Сеть клуба | http://<адрес сервера корта>:8016/feeder/… | Приложение тренажёра на телефоне в сети клуба, мост в клубе |
| Интернет | https://<адрес корта в интернете>/feeder/… | Облако производителя |
Оба адреса клуб сообщает при подключении. Методы, ключ и ответы одинаковы. Доступ из интернета клуб может отключить — тогда запрос оттуда получит 403.
Корт и зоны
Координаты — в метрах от угла корта: x поперёк от 0 до 10, y вдоль от 0 до 20, сетка на y = 10. Половина 1 — y < 10, половина 2 — y > 10.
Каждая половина разделена на девять зон: три ряда по глубине от сетки и три полосы поперёк. Зона записывается как половина-ряд-полоса, например 2-2-1 — половина 2, дальний ряд, центр. Границы всех восемнадцати зон отдаёт GET /feeder/info.
Мишени тренировки — одна или несколько зон на одной половине. Тренажёр стоит на половине мишеней, игрок — на другой и отбивает в мишени.
Методы
| Метод | Назначение |
|---|---|
GET /feeder/info | Версия, корты, размеры корта, зоны, пределы |
GET /feeder/time | Часы корта |
GET /feeder/session | Своя сессия на корте и состояние корта: идёт ли матч, упражнение, открыта ли «Пушка» с экрана |
POST /feeder/session/open | Открыть тренировку или подключиться к открытой с экрана корта |
POST /feeder/feed | Сообщить о поданном мяче |
GET /feeder/feeds | Поданные мячи с результатами |
GET /feeder/events | События с курсором и ожиданием |
POST /feeder/session/close | Закончить тренировку и получить итог |
Открыть тренировку
curl -X POST "http://<адрес сервера корта>:8016/feeder/session/open" \
-H "X-Integration-Key: <ключ тренажёра>" -H "Content-Type: application/json" \
-d '{"court": "Корт 4", "targets": ["2-2-0", "2-2-1"],
"machine": {"vendor": "Производитель", "model": "Модель"},
"program": {"name": "Глубокий драйв", "level": "3"}}'| Поле | Что это |
|---|---|
court | Название корта из GET /feeder/info; можно не указывать, если корт один |
targets | Зоны-мишени на одной половине |
attach | true — подключиться к тренировке «Пушка», которую игрок уже открыл на экране корта; мишени тогда берутся с экрана |
pass_code | QR-пропуск игрока из приложения клуба, если приложение тренажёра умеет его считать; тогда итог попадёт в личный кабинет игрока |
player | Имя для экрана корта, если пропуска нет |
voice | false — без голоса корта |
machine, program | Сведения о тренажёре и программе подач; сохраняются с итогом |
В ответе — сессия: её id, половина игрока player_half, мишени и сводка totals. Повторный запрос при живой сессии возвращает ту же сессию: после обрыва связи можно просто открыть заново.
Сообщить о поданном мяче
curl -X POST "http://<адрес сервера корта>:8016/feeder/feed" \
-H "X-Integration-Key: <ключ тренажёра>" -H "Content-Type: application/json" \
-d '{"session": "<id сессии>", "id": "ball-17", "speed_kmh": 65, "spin": "top",
"aim": {"x": 5.0, "y": 4.5}}'| Поле | Что это |
|---|---|
id | Номер мяча у тренажёра. Повтор запроса с тем же id не создаёт второй мяч |
t | Время вылета, секунды Unix. Если не указано, берётся время прихода запроса. Если часы тренажёра расходятся с часами корта больше чем на 2 секунды, тоже берётся время прихода, а в ответе есть clock_skew_s |
speed_kmh, spin, kind | Параметры подачи по данным тренажёра; сохраняются рядом с результатом |
aim | Куда целился тренажёр, координаты корта |
Запрос отправляется в момент вылета мяча: результат привязывается к подаче по времени. Если запрос идёт через интернет с заметной задержкой, передавайте t и сверяйте часы по GET /feeder/time.
Получать результаты
curl "http://<адрес сервера корта>:8016/feeder/events?court=%D0%9A%D0%BE%D1%80%D1%82%204&after=0&wait=20" \
-H "X-Integration-Key: <ключ тренажёра>"after — курсор из прошлого ответа (поле cursor), wait — сколько секунд ждать новых событий, не больше 25.
| Событие | Когда | Что внутри |
|---|---|---|
session_opened | Тренировка открыта | Мишени |
feed | Мяч принят | Номер n, ваш id, время |
feed_seen | Корт увидел приземление поданного мяча | seen: время, x, y, зона |
result | Известен исход мяча | status, result, сводка totals |
session_closed | Тренировка закрыта | Кем: partner или court; итог |
Исход мяча
status: "returned"— игрок отбил. Вresult:hit— попал ли в мишень,zone, точкаx,yиcode.status: "not_returned"— ответа нет: мяч не отбит или корт его не увидел. Эти два случая корт не различает и не выдаёт один за другой.
code | Что произошло с ответом игрока |
|---|---|
target | В мишень |
other_zone | В корт, но мимо мишени |
out | За линию |
net | В сетку |
glass | В стекло без отскока |
Те же данные списком — GET /feeder/feeds?after=<номер мяча>.
Закончить
curl -X POST "http://<адрес сервера корта>:8016/feeder/session/close" \
-H "X-Integration-Key: <ключ тренажёра>" -H "Content-Type: application/json" \
-d '{"session": "<id сессии>"}'В ответе — итог totals (подано, увидено кортом, отбито, в мишень, без ответа) и все мячи с результатами. Тренировка закрывается и сама: кнопкой «Стоп» на экране корта или после пяти минут без мячей — тогда придёт событие session_closed с closed_by: "court".
Отказы
| Код | code | Причина |
|---|---|---|
| 401 | — | Нет ключа или ключ неверный |
| 403 | — | Доступ из интернета на этом корте отключён |
| 400 | — | Корта с таким названием нет |
| 409 | court_busy | На корте идёт матч |
| 409 | drill_active | На корте идёт другое упражнение |
| 409 | feeder_taken | К корту уже подключён другой тренажёр |
| 422 | bad_targets | Мишени не заданы, такой зоны нет или мишени на двух половинах |
| 422 | bad_pass | QR-пропуск игрока не подошёл |
| 404 | no_session | Открытой сессии нет |
| 429 | too_many_feeds | Больше 3000 мячей в одной сессии |
Чего в версии 1 нет
- Скорости ответного удара игрока.
- Управления тренажёром со стороны корта: выбора программы подач под упражнение и уровень игрока. Это следующая версия, и для неё нужен интерфейс управления со стороны тренажёра.
- Отправки событий на адрес партнёра: корт сам соединений не открывает.