search

AliGeenius / Kimai-RFID-ESP

This programm is build for for an ESP8265/ESP8266 to communicate with the open source Kimai timetracking software via the API sending RFIDs to the server for starting/stopping timesheets.
20 stars 3 forks source link
esp8266 kimai-api kimai-bundle kimai-plugin kimai-timetracking kimai2 rfid sonoff

readme

Kimai RFID ESP

This programm is build for for an ESP8265/ESP8266 to communicate with the open source Kimai timetracking software via the API sending RFIDs to the server for starting/stopping timesheets. Written in C++ with PlatformIO Extension in VSCode.

Features

Little video preview

Intro

The programm is optimized for an ESP8265 controller but the performance should be the same on a ESP8266. I made it modular for the usage with/without serial output or/and a display. The platformio.ini file includes settings for you environment like board type, debug (for WiFiManager and HTTPClient) and board speed. In the main.ccp you can set the debug for the programm or enable/disable display.

All links to the needed parts are picked randomly on Amazon and maybe you can find cheaper modules on other sites.

First Start

The first start will set up a WiFi accesspoint that you can manage your settings for WiFi and your Kimai Server. Note: Actually theres no HTTPS client implemented!

alt text

If everything went well you are ready to run your Kimai remote device.

Usage

The usage is simply requesting the Remote Kimai API with the RFID and printing infos via serial or showing infos on display.

Status with display

(My camera is faster than the refreshing rate, so not everything seems to be correctly drawn on the display) After a successful start the menu is a analogue clock.

alt text

When reading a card and doing a successful request to the Kimai API the status of the timesheet will be shown.

alt text

Status without display or serial debug

Hardware

In my case I used a "Sonoff Touch" switch for the reader thats based on a ESP8265 contoller. But the librarys are also usable for the ESP8266 controllers. On the PCB of the Sonoff Switch is a useable LED that can used for displaying the status. Additionally a MFRC522 RFID reader is neccessary and if you want to a OLED display.

Sonoff hack ESP8265

Prerequirements

alt text

Preparation

The Sonoff switch consits of two PCBs the controller and power part that are connected with 4 pins. We just have to mod the upper controller PCB that's glued with double sided tape to the power PCB. The reader fits very well into the enclosure.

alt text

Theres a flat white diffusor for the relay status on top of the PCB. We have to remove it to reduce the height.

Now there are three ways:

  1. If you want to reuse the WiFi status LED of the switch you have to drill through the readers PCB
  2. Use the LED and modify the reader
  3. Dont use the LED and dont modify the reader

I encountered some problems with the reader when the controller board is really close to it. Only the cards delivered with the reader work well. I guess it's a shielding problem. But to get more distance to the controller PCB you need to change the readers crystal position so you can place the reader with the coil side to the enclosure.

You also should remove one of the 4 pins for the power PCB (see picture in wireing). Its connected to the relay but the pin (12) will be used for the reader.

Wireing

alt text

Description ESP GPIO Reader Pin Display Pin
Chip select 15 SDA
Clock 14 SCK
MOSI and LED 13 MOSI
MISO 12 MISO
Reset 0 RST
Data 4 SDA
Clock 5 SCL
Ground anywhere GND GND
VCC (3,3 V) anywhere VCC VCC

In my case it looks like this.

alt text

NodeMCU (ESP8266)

With the NodeMCU it should be a plug and play solution without soldering and just useing the jumper cables. But sometimes the board headers aren't presoldered so please have a look before buying.

Prerequirements

The GPIOs are compatibel with the ESP8265. Just use the upper table.

Software

  1. Clone or download this git.
  2. Open in PlatformIO
  3. Do your configstuff
  4. Flash your device

Building

You need PlatformIO to build the code. It should install all neccessary libraries automaticly. Choose your build environment in the plaform.ini file. Actually it's just building for the ESP8265. Change it to your needs. In this file you can also setup specific parameters like the debug settings for the HTTP client.

;example for the Sonoff hack
[platformio]
default_envs = esp8285

In the src/main.h file are additional settings for the usage with a display or for serial debugging.

#define SERIAL_DEBUG true
#define SERIAL_RESPONSE true
#define OLED_DISP true

You also should configure your timezone.

// edit it to your needs. The 7200 stands for + 2h
NTPClient timeClient(ntpUDP, "europe.pool.ntp.org", 7200, 60000);

Flashing

Sonoff

For flashing the Sonoff board you'll need an UART port eg. with an USB TTL adapter. For further details have a look for Sonoff flashing. there are several guides out.

ESP8266 with USB port

Just put in a micro USB cable and upload it..

Used librarys

Thank you guys for your great work!

Known issues