Skip to content

Getting started

reviewed: 3 July 2024

Быстрый старт в Telegram

Наш бот в Telegram является проводником в мир Ethelia — децентрализованного хранилища коротких данных на блокчейне Эфириум. Сегодня Ethelia используется как aльтернативный источник информации о качестве воздуха — участники проекта делятся значениями PM2.5 напрямую со своих очистителей, датчиков или умных устройств контроля окружающей среды. География проекта ограничена городом Бишкек 🇰🇬

Полный функционал бота доступен только зарегистрированным пользователям. Базовые функции управления анкетой регистрации:

  • /start — первоначальное заполнение регистрационной анкеты;
  • /reset — редактирование регистрационной анкеты;
  • /fetch — просмотр регистрационной анкеты;
  • /help — гайд по командам бота.

После успешной регистрации вам будет открыт доступ к основным командам бота:

  • /pm — отправка текущего значения PM2.5 с вашего сенсора;
  • /providers — просмотр текущих значений PM2.5;
  • /map — просмотр актуальной карты качества воздуха;
  • /livemap — просмотр анимированной карты изменения качества воздуха за прошедшие сутки;
  • /time — просмотр текущего времени на сервере;
  • /trxlog — просмотр списка последних транзакций в блокчейне, с помощью которых было выполнено сохранение значений PM2.5;
  • /synclog — просмотр лога синхронизации локальной базы данных и блокчейна;
  • /gethlog — просмотр лога блокчейн-клиента Geth;
  • /balance — просмотр баланса системного адреса;
  • /decode HEX_DATA — декодирование входных данных некоторой транзакции в блокчейне (команда для проведения аудита и верификации ранее отправленных в блокчейн значений);
  • /decompress HEX_DATA — декомпрессирование данных из блокчейна (команда для проведения аудита работы функций смарт-контракта из консоли Geth).

Мы будем благодарны, если вы отправите отчет при обнаружении багов или ошибок.

Быстрый старт в Web

Наша минималистичная административная панель использует механизмы авторизации/аутентификации на блокчейне в локальной PoA сети. Это привносит особенности, нехарактерные для традиционных web2.0 панелей.

Первое и наиболее заметное отличие — это ощутимая задержка порядка 20 секунд при первоначальном входе: после ввода логина и пароля выполняется авторизация на Ethereum узле и последующее развёртывание смарт-контракта аутентификации. Несмотря на производительную локальную сеть на PoA консенсусе и быструю генерацию блоков, развёртывание и последующее взаимодействие со смарт-контрактом занимает некоторое время. Поэтому после того, как вы ввели учётные данные и нажали Log In, расслабьтесь, глубоко вдохните и дождитесь успешного входа.

Второе отличие — мы вдохновились расхожим в области IoT подходом, в котором рендеринг, а также вся логика обновления виджетов и компонентов перенесены в браузер пользователя. Строго говоря, мы имеем фронт-энд в браузере и бэк-энд на сервере, обмен данными между которыми выполняется через RESP API. Особенность в том, что для нивелирования атак типа MITM в фоновом режиме производится обновление токена доступа. Учитывая задержки, накладываемые работой смарт-контракта в блокчейне, интерактивные элементы панели вроде ссылок, кнопок и т.д. блокируются на короткое время во избежание использования устаревшего токена.

Просмотреть актуальный токен доступа, а также ранее отправленные значения PM2.5, можно на вкладках Home и Ethelia соответственно.

Токен доступа — access token

Токен доступа публикуется на вкладке Home административной панели в поле ASC token после успешного входа:

Session details
The session will expire in XX seconds
The session is authenticated on Ethereum node for account 0x2820f8529b288257fd9f9c73ee470591e9975f88, scope is address
Secure private key is 0xa322f5629b495fd290bc2f9c4ac37d26e4cc9bfbe85ae76863ed72f0ae0f7964
ASC token: 0xc5d0413dd074cab5e5b0a64531b4c1f1323e8a41054334008fac4e33963be0fc
Cookie: 0xc5d0413dd074cab5e5b0a64531b4c1f1323e8a41054334008fac4e33963be0fc

Публикация нового значения PM2.5

Для публикации нового значения PM2.5 следует отправить POST запрос на https://pheix.org/api. Пример запроса:

{
    "credentials": {
        "token": "ASC_TOKEN"
    },
    "method": "GET",
    "route": "/api/ethelia/event/store",
    "payload": {
        "code": "20240301",
        "topic": "pm2.5",
        "payload": {
            "sensorvalue": 15,
            "sensordevice": "Xaomi Air Purifier 4 Pro",
            "enrichment": {
                "position": {
                    "lng": 74.607386,
                    "lat": 42.832880
                },
                "title": "Secret location in Bishkek"
            }
        }
    }
}

ASC_TOKEN — это ваш актуальный токен доступа из административной панели.

Краткое описание полей секции payload.payload:

  1. enrichment.position — широта и долгота текущей геолокации;
  2. enrichment.title — подпись, которая будет будет отображаться на карте;
  3. sensorvalue — значения сенсора PM2.5;
  4. sensordevice — название устройства или сенсора;
  5. code и topic могут быть произвольными, мы рекомендуем использовать уникальные и удобные для последующего поиска фразы или словосочетания.

Пример публикации данных с Xiomi Smart Purifier 4 Lite

Если вы являетесь обладателем очистителя воздуха Smart Purifier 4 Lite компании Xiomi, а также пользователем ОС семейства Linux, вы можете автоматизировать публикацию значений PM2.5. Общая пошаговая схема автоматизации выглядит следующим образом:

flowchart TD A(Получение Xiaomi Home токена из облачного хранилища) --> B(Получение значений PM2.5 с Purifier 4 Lite с помощью утилиты miiocli) B --> D(Получение Ethelia токена и публикация значения PM2.5)

Для получение Xiaomi Home токена из облачного хранилища воспользуйтесь консольным скриптом Xiaomi Cloud Tokens Extractor для ОС семейства Linux:

bash <(curl -L https://github.com/PiotrMachowski/Xiaomi-cloud-tokens-extractor/raw/master/run.sh)

После успешной авторизации в облаке скрипт выведет подробную информацию о ваших устройствах (модель, название, идентификатор, MAC и IP адреса, токен доступа):

Username (email or user ID): ****
Password:                    ****

Server (one of: cn, de, us, ru, tw, sg, in, i2)
Leave empty to check all available: cn

Logging in...
Logged in.

Devices found for server "cn" @ home "99*********1":
   ---------
   NAME:     Xiaomi Smart Air Purifier 4 Lite
   ID:       5*******5
   MAC:      CC:**:**:**:**:36
   IP:       192.168.0.100
   TOKEN:    4e******0ab*******************5
   MODEL:    zhimi.airp.rma2

Токен доступа является постоянным и создаётся при добавлении устройства в облако.

Далее следует опросить ваш Xiaomi Smart Air Purifier 4 Lite по протоколу MIoT. Для этого воспользуйтесь утилитой miiocli:

miiocli genericmiot --ip 192.168.0.100 --token 4e******0ab*******************5 get_property_by 3 4

В случае успеха утилита выведет в консоль JSON следующего вида:

[
  {
    "did": "3-4",
    "siid": 3,
    "piid": 4,
    "code": 0,
    "value": 2
  }
]

Значение value — это текущее значение PM2.5 сенсора Xiaomi Smart Air Purifier 4 Lite.

Для получения ASC_TOKEN Ethelia воспользуйтесь следующей командой (адрес ADDR и пароль PASS вам будут назначены после успешной регистрации в Telegram):

ADDR="0x0000000000000000000000000000000000000000" && \
PASS="*****" && \
curl -X POST https://pheix.org/api \
     -H 'Content-Type: application/json' \
     -d '{"credentials":{"login":"'$ADDR'","password":"'$PASS'"},"method":"GET","route":"/api/admin/auth"}' \
| jq .content.tparams.tx | tr -d \"

После успешного завершения в консоль будет выведен токен доступа ASC_TOKEN:

0x1d12b10e88eee356d1f8439993a074b45081b88695c27041d6313b9e63d0be49

⚠️ Внимание! Токен доступа ASC_TOKEN действителен в течении 1 минуты — публикация нового значения должна быть выполнена оперативно.

Далее следует изменить JSON универсальный запрос публикации значения PM2.5:

  • добавить актуальный токен доступа ASC_TOKEN;
  • вставить текущее значение PM2.5 с Xiaomi Smart Air Purifier 4 Lite;
  • указать вашу геолокацию.

И выполнить публикацию с помощью команды:

CODE=`date +%s` && \
TOKEN="0x1d12b10e88eee356d1f8439993a074b45081b88695c27041d6313b9e63d0be49" && \
VALUE="2" && \
curl -X POST https://pheix.org/api \
     -H 'Content-Type: application/json' \
     -d '{"credentials":{"token":"'$TOKEN'"},"method":"GET","route":"/api/ethelia/event/store","payload":{"code":"'$CODE'","topic":"pm2.5","payload":{"sensorvalue":'$VALUE',"sensordevice":"Xaomi Air Purifier 4 Pro","enrichment":{"position":{"lng":74.607386,"lat":42.83288},"title":"Secret location in Bishkek"}}}}'

После успешной публикации значения PM2.5 сервер пришлёт следующий ответ:

{
  "content": {
    "chainid": 62,
    "event": "pm25",
    "notification": false,
    "result": "success"
  },
  "msg": "/api/ethelia/event/store fetch is successful",
  "render": "0.837662634",
  "status": 1
}

Просмотр актуальных значений PM2.5

Для просмотра полного списка значений PM2.5 используется следующий POST запрос на https://pheix.org/api:

{
    "credentials": {
        "token": "ASC_TOKEN"
    },
    "method": "GET",
    "route": "/api/ethelia/event/search",
    "payload": {
        "search": {
            "target": "1",
            "value": "*"
        }
    }
}

ASC_TOKEN — это ваш актуальный токен доступа из административной панели. Поле payload.search.target используется для поиска по текущим значениям PM2.5:

  1. значение 1 — поиск по payload.code;
  2. значение 2 — поиск по payload.topic.

Поле payload.search.value используется совместно payload.search.target для поиска конкретного значения payload.code или payload.topic. Например, следующий запрос выполнит поиск значений PM2.5 с payload.code равным 1-ETHL-2024:

{
    "credentials": {
        "token": "ASC_TOKEN"
    },
    "method": "GET",
    "route": "/api/ethelia/event/search",
    "payload": {
        "search": {
            "target": "1",
            "value": "1-ETHL-2024"
        }
    }
}

При поиске может быть использован метасимвол * для вывода всех значений.