elabFTW Guide

In order to create a script that uploads directly to elabFTW, you will need to have the file eLabFTW_config_api2_semilab.py present within the same directory as the script using elabFTW functionality:

import os
import time
import datetime
import elabapi_python
from elabapi_python.rest import ApiException
import json

""" **************************************************
inspired by
https://alexgu2008.github.io/elabftw_api_support/

for further documentation:
https://doc.elabftw.net/api/elabapi-html/
for further examples:
https://github.com/elabftw/elabapi-python

author: K. Zojer (April 2024)
last_edit: R. Steentjes (April 2024)
**************************************************
""" 
#########################
#         CONFIG        #
#########################
API_HOST_URL = 'https://elabftw.tugraz.at/api/v2'
# API_KEY needs to be generated on the eLabFTW website!
# See: https://lampz.tugraz.at/~hadley/semi/elabftw/elab.html
API_KEY = '---ENTER-YOUR-APIKEY-HERE---'
# USER_LAST_NAME is really just the real last name of the TUGRAZonline user,
# including special characters! E.g. "Großbäcker"
USER_LAST_NAME = '---ENTER-YOUR-USER-LASTNAME-HERE---'
#########################
#      END CONFIG       #
#########################

class Helper_elabftw:

def get_myuserId(self):
        
        usersApi = elabapi_python.UsersApi(self.api_client)

uresponse = usersApi.read_users()

target_user_lastname = USER_LAST_NAME

for user in uresponse:
            
            if user.lastname == target_user_lastname:
                #print("User ID of ", user.lastname," ", user.firstname, ": ", user.userid)
                self.userid = user.userid    
        
        return self.userid

def __init__(self):
        # Configure the api client
        self.configuration = elabapi_python.Configuration()
        self.configuration.api_key['api_key'] = API_KEY
        self.configuration.api_key_prefix['api_key'] = 'Authorization'
        self.configuration.host = API_HOST_URL
        self.configuration.debug = False
        self.configuration.verify_ssl = True
        # create an instance of the API class
        self.api_client = elabapi_python.ApiClient(self.configuration)
        # fix issue with Authorization header not being properly set by the generated lib
        self.api_client.set_default_header(header_name='Authorization', header_value=API_KEY)
        print(" user id:  ", self.get_myuserId())

"""==================================================================================== 
        provides the experiment_ID for the experiment matching the experimental title

input:
            experiment_title ... title of the experiment (type: string)
    """
    def get_existing_experiment(self, exp_title):

# default response if experiment is not found:
        experiment_ID = -1
        experimentsApi = elabapi_python.ExperimentsApi(self.api_client)

response = experimentsApi.read_experiments(owner=self.userid) 
        for exp in response:
        
            if exp.title == exp_title:
                print("Experiment ID: ", exp.id, " ", exp_title)
                experiment_ID = exp.id
                #print(type(response[0]))
            else: 
                print("Experiment does not exist yet.")
        return experiment_ID

"""==================================================================================== 
        provides the experiment_ID for newly generated experiment with given title and current date

input:
            experiment_title ... title of the experiment (type: string)
    """

def create_experiment(self, exp_title):

experimentsApi = elabapi_python.ExperimentsApi(self.api_client)
        current_date = datetime.date.today()
        response_body, status_code, response_headers = experimentsApi.post_experiment_with_http_info(
            body={'title': exp_title,
                'date': current_date,
                'tags': ['#semilab', '#SS2024']})
        #print(status_code)
        #print(response_headers)
        experiment_ID = response_headers["Location"].split("/")[-1]
        canread = {"base": 30, # everyone in the team of user
                "teams": [7], # 7 = Institute of Solid State Physics
                "teamgroups": [],
                "users": [83, 117, 272]} # 83 = Karin Zojer, 117 = Peter Hadley, 272 = Robbin Steentjes
        experimentsApi.patch_experiment(experiment_ID, body={'canread': json.dumps(canread)})
        response = experimentsApi.patch_experiment(experiment_ID, body={'title': exp_title})
        
        return experiment_ID
        
    """==================================================================================== 
    provides the experiment_ID for the experiment matching the experimental title

input:
        experiment_title ... title of the experiment (type: string)
    """
    def set_experiment(self, experiment_title):

experimentsApi = elabapi_python.ExperimentsApi(self.api_client)
        experiment_ID = self.get_existing_experiment(experiment_title)

if experiment_ID == -1:
            print(" Create experiment: ", experiment_title)
            experiment_ID = self.create_experiment(experiment_title)
        
        return experiment_ID

""" 
        uploades a file to the experiment specified by experiment_ID

input:
            experiment_ID   ... ID of experiment
            filename        ... name of the file to be uploaded
                                merge path with filename if file is not in the local directory
    """
    def upload_file(self,experiment_ID, filename):
        
        uploadsApi = elabapi_python.UploadsApi(self.api_client)
        #local_file_path = #r".\\ "  
        
        #try: 
            #uploadsApi.post_upload('experiments', experiment_ID, file=local_file_path+filename, comment='Uploaded with APIv2')
        uploadsApi.post_upload('experiments', experiment_ID, file=filename, comment='Uploaded with APIv2')
        #except ApiException as e:
        #    print("Exception when calling UploadsApi->postUpload: %s\n" % e)
        return

This library provides a convenient set of functions to push measured data immediately into an electronic notebook.
This wrapper library relies on the elabapi_python package that is preinstalled on the measurement computers. You will need to customize this library. The neccessary adaptions will be shown in a dedicated section below.

Basic setup

Create and add your own token id="token"

(1) Log into the elabFTW page, on the top right corner click the account icon and select USER PANEL in the dropdown menu.

Then go to API KEYS (1), under Create new key enter a name (2), e.g., your lab_group or similar, select Read/Write permissions (3) and click Generate An API Key (4). You will now be shown a long string, copy this somewhere safe.

ATTENTION
The key will be shown to you only once: Do not leave the page until you have stored the key in an appropriate place!
Refrain from uploading any file containing your key to elabFTW !
Should you loose this key, you can delete it from the list and generate a new one.

(2) Within the earlier mentioned eLabFTW_config_api2_semilab.py, you will find a section CONFIG with the line API_KEY = '---ENTER-YOUR-APIKEY-HERE----' . Replace the string ---ENTER-YOUR-APIKEY-HERE---- with your newly created token.
Replace in the next line USER_LAST_NAME = '---ENTER-YOUR-USER-LASTNAME-HERE----', with your last name, that is just the real last name associated to your TUGRAZonline user account. Enter this last name literally, including any special characters, e.g., "Großbäcker". Upon being called in your working script, this function uses your token as authorization to control the data transmitted to elabFTW.

Give team members access

Once the experiment is set up correctly, go to the elabFTW page and find it under the Experiments tab. Click Edit (the pen symbol), then click the Visibility. Therein, you should set both options to the smallest possible group that you have access to. For example, it could be all members of your lab group. Each user can be asked for individually by providing her/his/their user name.

In order to find your data in the experiment tab, you can use the tag that is created (#semilab) and your own tags.

Sample script

This is an example for ELabFTW integration into a diode measurement (diode_characteristic.py):

from KeithleyV15 import SMU26xx
import matplotlib.pyplot as plt
import time
import datetime
import csv
import numpy as np

#for use of ELABFTW
import os
import elabapi_python
import eLabFTW_config_api2_semilab as eLab
import json

"""
EXAMPLE: characteristic curve of a diode

Schematic:

--------------
    |            |
  -----         -|-
  | A | SMU     \|/
  -----         -|-
    |            |
    --------------

"""

""" ******* Connect to the Sourcemeter ******** """

# initialize the Sourcemeter and connect to it
# you may need to change the IP address depending on which sourcemeter you are using
sm = SMU26xx("TCPIP0::129.27.158.188::inst0::INSTR")

# get one channel of the Sourcemeter (we only need one for this measurement)
smu = sm.get_channel(sm.CHANNEL_A)

""" ******* Configure the SMU Channel A ******** """
#define a variable "current range" to be able to change it quickly for future measurements

current_range = 1e-8
current_range_for_name = str(current_range)

# reset to default settings
smu.reset()
# setup the operation mode of the source meter to act as a voltage source - the SMU generates a voltage and measures tcurrent
smu.set_mode_voltage_source()
# set the voltage and current parameters
smu.set_voltage_range(20)
smu.set_voltage_limit(20)
smu.set_voltage(0)
smu.set_current_range(current_range)
smu.set_current_limit(current_range)
smu.set_current(0)

""" ******* For saving the data ******** """

#some suggestions for improvement of the data saving
    #the file name should identify the file uniquely
    #therefore specifying for example the voltage range, and the
    #type of characteristic (U/I, U/R, etc...) is suggested

# Create unique filenames for saving the data
time_for_name = datetime.datetime.now().strftime("%Y_%m_%d_%H%M%S")
filename_csv = 'Diode_' + 'current_range_' + current_range_for_name + '_' + time_for_name +'.csv'
filename_pdf = 'Diode_' + 'current_range_' + current_range_for_name + '_' + time_for_name +'.pdf'

# define the title of your experiment, under this name the experiment will be stored in ElabFTW
exp_title = "Red Diode Measurements"

#initializing a CSV file, to which the measurement data will be written - if this script is used to measure anothcharacteristic than the U/I curve, this has to be changed
# Header for csv
with open(filename_csv, 'a') as csvfile:
        writer = csv.writer(csvfile, delimiter=';',  lineterminator='\n')
        writer.writerow(["Voltage / V", "Current / A"])

""" ******* Make a voltage-sweep and do some measurements ******** """

#some suggestions for the improvement of the measurement process
    #it would be nice to have a primary measurement, in which the
    #type of junction was be determined and a parameter was set
    #that indicated the forward direction of the junction
    #this primary measurement could also be executed and inlcuded
    #in the file name
    #this procedure would spare us the time of finding the forward
    #direction

# define sweep parameters
sweep_start = -2.50
sweep_end = 2.5
sweep_step = 0.01
steps = int((sweep_end - sweep_start) / sweep_step)

# define variables we store the measurement in
# rename if needed
data_current = []
data_voltage = []

# enable the output
smu.enable_output()

# step through the voltages and get the values from the device
for nr in range(steps):
    # calculate the new voltage we want to set
    voltage_to_set = sweep_start + (sweep_step * nr)
    # set the new voltage to the SMU
    smu.set_voltage(voltage_to_set)
    # get current and voltage from the SMU and append it to the list so we can plot it later
    [current, voltage] = smu.measure_current_and_voltage()
    data_voltage.append(voltage)
    data_current.append(current)
    print(str(voltage)+' V; '+str(current)+' A')
    # Write the data in a csv
    with open(filename_csv, 'a') as csvfile:
        writer = csv.writer(csvfile, delimiter=';',  lineterminator='\n')
        writer.writerow([voltage, current])

# disable the output
smu.disable_output()

# properly disconnect from the device
sm.disconnect()

""" ******* Plot the Data we obtained ******** """

#use plt instead of semilogy to plot in chartesian axis
plt.semilogy(data_voltage, np.abs(data_current),'x-', linewidth=2)

# set labels and a title
#suggestion: include some more information about the measurement (ref CSV file title)
plt.xlabel('Voltage / V', fontsize=14)
plt.ylabel('Current / A', fontsize=14)
plt.title('Characteristic curve of a diode', fontsize=14)
plt.tick_params(labelsize = 14)

plt.savefig(filename_pdf)

# Connect to eLab

elab_manager = eLab.Helper_elabftw()
experiment_ID = elab_manager.set_experiment(exp_title)
print(experiment_ID)

# Upload files to eLab
filename_scr = __file__
elab_manager.upload_file(experiment_ID, filename_csv)
elab_manager.upload_file(experiment_ID, filename_pdf)
elab_manager.upload_file(experiment_ID, filename_scr)

#show plot
plt.show()

Setting up and working with elabFTW

Basic setup

Log in at elabFTW

Create and add your own token id="token"

Give team members access

Sample script