TracePRO traceapi

POZOR: Tento text popisuje knihovnu traceapi pro Python3. Pokud potřebujete jiný způsob přístupu, zkuste simpleapi, která je jednodušší, ale pro většinu účelů dostatečná.

Instalace

Měli byste mít k dispozici balíčky:

  • tracelib

  • traceapi

Oba nainstalujte. traceapi závisí na requests a jsonrpc_requests.

Součástí traceapi jsou i moduly sampleXX.py, ve kterých jsou ukázky kódu.

  • sample01.py: Přihlášení, nastavení objednávky a operace, zápis operace k jednotce.

  • sample02.py: Pokud to dovoluje nastavení výrobní objednávky na serveru, api může založit jednotku.

  • sample03.py: Ukázka použití funkcí pro řízení robota: teststart / testrun / testend.

  • sample04.py + sample04.ini: Ukázka inicializace knihovny z ini souboru.

  • sample05.py: Ukázka funkce getitemdetails.

Inicializace

Nejprve musíte vytvořit instanci třídy API. Je několik možností, jak to udělat.

Konfigurační soubor v kódu

Nejlepší je mít konfiguraci (url api a pracoviště) v konfiguračním souboru, např. takto:

; c:/testprogram/config.ini
[tracepro_client]
api_url=https://traceability.cz/api
wp=1015

Konfigurační soubor je windows-like ini soubor. Musí obsahovat sekci s klíči api_url (url API TracePRO), a wp (číslo pracoviště). O ostatní sekce konfiguračního souboru se traceapi nestará.

import traceapi

api = traceapi.API(config_file="C:/testprogram/config.ini", section="tracepro_client")

Konfigurační soubor na příkazové řádce

Pokud spouštíte aplikaci s cestou ke konfiguračnímu souboru na příkazové řádce, je možné říct, knihovně, jaký parametr to je, a knihovna si jméno souboru z parametrů vyčte. Např. pokud se testovací program spouští:

python test_prog_runner.py --config-file=c:/testprogram/config.ini

tak kód pro inicializaci traceapi může vypadat takto:

import traceapi

api = traceapi.API(arg_prefix="--config-file=", section="tracepro_client")

Předání api_url a wp jako parametrů

Také je možnost předat parametry api_url a wp přímo volání konstruktoru. Např. takto:

import traceapi

api = traceapi.API(api_url="https://traceability.cz/api", wp=1011)

To ale nedoporučujeme, protože je možné, že v konfiguračním souboru v budoucnu přibydou další parametry.

Testovací verze API

Pokud jako api_url zadáte DUMMY, pak se traceapi nebude připojovat na server, pouze bude vypisovat volání do logovacího systému Pythonu, a vracet (login, getorder) bude předdefinované hodnoty. Tohle platí, ať už nastavíte api_url přímo, nebo přes konfigurační soubor.

Lze použít pro jednoduché testování, ale doporučujeme testovat i s demo instancí na https://traceability.cz/api.

Obecné

Obecně vzato funkce API při chybě vyvolají vyjímku. Vpostatě není úplně potřeba číst návratovou hodnotu, buď na ní nezáleží, nebo si ji API uloží. Např. voláním funkce login se modifikuje API.worker. Hodnotu pak knihovna automaticky použije při dalších voláních API. Podobně je to s funkcí pro ověření výrobní objednávky a operace.

Přihlášení, funkce login

Funkce login dostane jako parametr číslo nebo barkód zaměstnance. Vrátí strukturu zaměstnance.

api.login(1021)
api.worker == {"id": 1021, "name": "Martin", "erp_id": ""}

Kontrola výrobní objednávky

Jde o to zkontrolovat, že výrobní objednávka existuje, a má požadovanou operaci. Funkce vrátí strukturu výrobní objednávky. Nastaví api.order na strukturu objednávky, a api.op na číslo operace.

  • První parametr je jméno výrobní objednávky

  • Druhý parametr je číslo operace

order = api.getorderoperation("PO-PLAYGROUND", 20)
order == {
  'id': 23,                       # id objednavky v systemu
  'item': 'SIMPLEAPI',            # typ polozky
  'erp_ref': 'PO-PLAYGROUND',     # jmeno objednavky
  'status': 1,                    # stav - 1 - aktivni
  'flags': 1,                     # dalsi parametry
  'amount': 100,
  'mptp': 2,
  'mpcount': 0,
  'barcode_mp': '',
  'barcode_pcb': '',
  'operations': [                 # pole operaci
    {'id': 118, 'order_id': 23, 'op': 10, 'act': 1001, 'name': '', 'desc': '', 'flags': 0},
    {'id': 119, 'order_id': 23, 'op': 20, 'act': 3001, 'name': '', 'desc': '', 'flags': 0}
  ],
  'opdict': {                     # slovnik operaci - klic je cislo operace
    10: {'id': 118, 'order_id': 23, 'op': 10, 'act': 1001, 'name': '', 'desc': '', 'flags': 0},
    20: {'id': 119, 'order_id': 23, 'op': 20, 'act': 3001, 'name': '', 'desc': '', 'flags': 0}
  },
  'opdata': [                    # data operaci
    {'id': 1, 'order_id': 23, 'op': None, 'key': 'INFO', 'value': 'Přes simpleapi NELZE automaticky vytvořit položku.'},
    {'id': 2, 'order_id': 23, 'op': None, 'key': 'AUTOCREATE_ITEM', 'value': '0'}
    {'id': 3, 'order_id': 23, 'op': 20, 'key': 'PROGRAM', 'value': 'ict_simpleapi'}
    {'id': 4, 'order_id': 23, 'op': 20, 'key': 'VERSION', 'value': '1.0.23'}
  ]
}
api.order
api.op

Připomínám, že pokud objednávka není, nebo pokud operace není v objednávce, funkce vyvolá vyjímku. Objednávka a operace se uloží v api, a použije se pro další volání canaddorderop, addop.

U jednoúčelových zařízení (např. ICT) by asi bylo dobré, aby uživatelské rozhraní předvyplňovalo naposled zadanou výrobní objednávku a operaci.

Parametry operací

Na serveru je možné nastavit různé parametry pro celou výrobní objednávku, nebo pro jednotlivé operace. Klienti TracePRO tyto parametry dostanou, a mohou je použít. V příkladě nahoře si všimněte:

order['opdata']
order['opdata'][2]['key'], order['opdata'][2]['value']
order['opdata'][3]['key'], order['opdata'][3]['value']

Zde je uloženo jakési jméno programu a verze. Proces může být ve firmě nastaven tak, že tyto hodnoty se dostanou z prodejní objednávky do výrobní objednávky v ERP, odtamtud pak automaticky do TracePRO, a z TracePRO je může vyčíst např. ICT a používat.

Kus z jiné objednávky

Normální chování TracePRO je takové, že když se hledá jednotka pomocí barkódu výrobku a výrobní objednávky, je možné, že jednotka s tímto barkódem je v jiné výrobní objednávce na stejný typ výrobku. V tom případě je vše vpořádku, situace, že se smíchají jednotky stejného typu z různých výrobních objednávek je běžná. I traceapi s takovou situací počítá a normálně funguje.

Test zapsání operace

Po načtení barkódu operace je vhodné otestovat, jestli bude možné operaci zapsat. Kontroluje se, zda byly provedeny předchozí operace, ale je možné, že server kontroluje i další parametry (pracoviště, pracovníka, …)

Pracuje s objednávkou a operací nastavenou ve funkci API.getorderoperation.

api.canaddorderop("TS000000012")

Zapsání operace

Výsledek testu/operace můžete zapsat pomocí funkce addop. Lze zapsat výsledek a data. Tato funkce lze také použít k zapsání operací, na kterých se nenačítá barkód. V tom případě se zapíše jen počet (v tomto případě se přičte jednička k počtu vyrobených kusů).

  • První parametr je barkód položky, pro výrobu bez barkódů použijte hodnotu None.

  • Druhý parametr je výsledek, 0 znamená OK, nenulová hodnota znamená chybu

  • Třetí parametr je pole dat. Pole dat je sekvence trojic (TŘÍDA, KLÍČ, HODNOTA)

    • TŘÍDA - jedna z tracelib.defs.OPDATA_* konstant

    • KLÍČ - jméno, pod kterým se data uloží

    • HODNOTA - jakákoliv hodnota

from tracelib import defs

api.addop("TS000000012", 0, [])


api.addop("TS000000061", 1, [
    # Examples of values:
    # the program name:
    (defs.OPDATA_PARAM, "prog", "isim_module_ict_1.3.1"),

    # any value obtained from the device
    (defs.OPDATA_VAL, "imsi", "ABCD434333A383DF"),

    # a defect which is not a measured value
    (defs.OPDATA_E_DEFECT, "front_wheel", "punctured"),

    # a defect on a measured value
    (defs.OPDATA_E_VAL, "I_R23(A)", "23"),

    # a result of a measurement
    (defs.OPDATA_I_VAL, "U_R23(V)", "4.92"),
])

Informace o jednotce

Funkci getitem můžete použít pro získání základních informací o jednotce. Z pohledu uživatele API mohou být zajímavá asi jen pole:

  • tp: Typ jednotky, jedna z konstant tracelib.defs.ITEM_TP*

  • bad: Nastaveno na nenulovou hodnotu pokud je jednotka špatná (vyzmetkovaná nebo bad-mark)

ret = api.getitem("TS000000012")
ret == {'id': 4981, 'barcode': 'TS000000001', 'order_id': 23, 'tp': 3, 'bad': 0}

Výsledek operace ze serveru

Tato funkce umožňuje zjistit, zda nastavená operace už byla na sériovém čísle provedena. Funkce getopresult vrátí výsledek posledního provedení právě nastavené operace (na právě nastavené objednávce). Připomínám, že výsledek/result 0 znamená úspěch, nenulová hodnota znamená chybu. Např.:

order = api.getorderoperation("PO-PLAYGROUND", 20)
ret = api.getopresult("TSNONEXISTING")
ret == {}

ret = api.getopresult("TS000000060")
ret == {
    'result': 0,
    'data': [(21, 'U_pokus59(V)', '59')],
    'tm0': '2022-05-13T11:38:52', 'tm1': '2022-05-13T11:38:52',
    'op': 20, 'act': 3001, 'wp_id': 1015, 'workers': '1010',
}

Seznam všech operací provedených na jednotce

Pokud nestačí informace o výsledku poslední operace, je možné vyžádat si seznam všech operací provedených na jednotce. Funkce getitemdetails vrátí stejné údaje jako getitem, ale přidá ještě seznam operací do pole woperations. Operace budou seřazeny od nejstarší po nejnovější. Struktura slovníku operace je stejná, jako vrací funkce getopresult. Ukázku najdete v sample05.py.

ret = api.getitemdetails("TS000000012")
for op in ret["woperations"]:
    print(op)
# každá operace:
# {'op': 20, 'act': 3001, 'wp_id': 1015, 'worker_grp_id': 75, 'workers': '1010',
#  'tm0': '2022-05-13T13:47:35', 'tm1': '2022-05-13T13:47:35',
#  'result': 1, 'op_num': 41,
#  'data': [(21, 'VBUSA_V', '5.001'), (21, 'VBUSA_I', '0.008'), ]
# }

Ovládání robota

Jako podpora pro případné napojení na testovacího robota bylo připraveno rozhraní funkcí, které mají robota informovat o průběhu testování jednotky. Funkce jsou momentálně prázdné.

  • teststart(barcode, timeinterval) - informuje o tom, že test úspěšně začal, a očekává se, že bude pokračovat max. timeinterval sekund.

  • testrun(barcode, timeinterval) - informuje o tom, že test úspěšně pokračuje, a očekává se, že bude pokračovat ještě max. timeinterval sekund.

  • testend(barcode, test_type, result, info) - informuje o tom, že test skončil. Parametry se uloží do databáze, výsledek se pošle robotovi, aby věděl, zda má dát kus do špatných nebo dobrých. Parametry:

    • test_type - typ testu, např. ICT, FCT.

    • result - výsledek - 0 znamená OK.

    • info - dopňující textová informace, např. o chybě.

Myšlenka je taková, že po položení desky do fixtury robot čeká krátkou dobu (5s), zda test začne - čeká na zprávu teststart. Pokud zpráva nepřijde, desku odstraní a buď dá do špatných nebo zkusí znovu. Pokud zpráva přijde, čeká max timeinterval sekund na další zprávu. Pokud zpráva nepřijde, předpokládá, že test se nějak zasekl, a desku mu vyrve. Pokud přijde zpráva testrun, znamená to, že test ještě běží, a čeká dalších timeinterval sekund. To se může libovolně opakovat. Pokud přijde zpráva testend, robot podle výsledku dá desku do špatných nebo dobrých, a informace o výsledku testu zaznamená.