SAPIUS MANUAL

Sapius Manual

From the project folder to the compiled block. Everything you need to get started on your own.

1. What Sapius is

Sapius is the PLC programmer’s virtual colleague: it reads the project, writes the code, takes it into the manufacturer’s environment, compiles, fixes the errors and keeps the results and the evidence. You describe the result; the decisions stay yours and stay on record in the project. You can also ask it for reasoned suggestions, for example on how to organise a block’s parameters.

In TIA Portal (V16–V20) it works on a verified copy of your project: it writes the blocks in SCL, imports them, compiles and corrects until there are zero errors. It creates UDTs, DBs and tags, reads the hardware, and prepares WinCC HMI screens and tags as well as tests with PLCSIM Advanced. For Rockwell, CODESYS, Schneider and TwinCAT, and for Optix and Weintek HMIs, it generates and edits the sources and project files, ready to import into the manufacturer’s environment (chapter 8).

For diagnostics it reads values from the PLC over S7, Modbus TCP, OPC UA and EtherNet/IP. PLC brand, engineering environment and protocol are separate choices: you make them, project by project.

Every write goes through your yes, or through the approval mode you choose (chapter 7). Sapius downloads nothing to the CPU: you do the download yourself from TIA, once you are happy with the work.

2. Installation

Requirements

Sapius runs on 64-bit Windows 10 (1809 or later) and on Windows 11, with WebView2. The agent engine is included in the installer. You need an account at sapiusportal.it, as a private customer or as a business, and the AI you prefer: your own AI account, your own compatible API, Sapius-managed AI or local AI on your PC. For TIA Portal: V16–V20 with Openness, .NET Framework 4.8 and your Windows user in the Siemens TIA Openness group. For other brands, the manufacturer’s engineering software with its licences.

Installing Sapius

Download the installer from the Download section of your account area. If you are updating, close Sapius before running it: projects, accounts and preferences stay where they are. The program installs to C:\Program Files\Sapius; you can add sapius to the PATH. Projects and settings are in %LOCALAPPDATA%\SapiusV2, and uninstalling keeps them.

Sapius_Setup_<version>.exe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART

Account and AI

Sign in with the email and password of your Sapius account. If you use your own ChatGPT account, press Connect ChatGPT and complete the OpenAI sign-in in the browser: the two sign-ins are separate. To change Sapius account, use Sign out; to change ChatGPT account, disconnect it in the account panel and connect it again. Your projects stay on the PC.

Updates and knowledge

When an update is available, Update now appears: Sapius checks the download against the published hash and then starts the installer. You can postpone it. On first launch you choose whether to contribute to the shared technical knowledge: it is optional, and you can change it whenever you like in the settings (chapter 6).

Sapius language

Choose Italian, English, Spanish, German or French with the language button at the top or from Settings → Language, even before signing in. The choice stays saved on this PC, and switching language keeps your drafts, attachments and work in progress. In new conversations the assistant uses the language you chose, unless you ask for another. PLC code, tag names, documents and original technical messages stay as they are.

Icons, columns and help

The toolbar uses icons with tooltips: log, manual (the book), language, settings and sign out. The book opens this manual in the language you chose. Drag the border between Projects and chat, or between chat and details, to change the widths, which are saved on this PC. From the keyboard, select the divider and use the arrow keys; Shift increases the step, and Home or a double-click restores the initial width. In narrow windows the panels adapt to the available space.

For a new project, use the + next to Projects (New project), fill in the name, customer and revision, and confirm. With a project open, the large button at the top creates a new conversation instead. You can ask Sapius how to use the application: it knows the guide for the installed version and explains the steps.

3. Trial, pricing and licences

The 7-day free trial

Seven days on one project, with Officina, no card required. Create your account, as a private customer or as a business, verify your email and accept the terms of sale with the code you receive by email (six digits, valid for 15 minutes). In Sapius press Activate the 7-day trial, or use /prova. During the trial you use your own AI account, your own compatible API or local AI.

Each account and each PC is entitled to one trial. When it ends there is no automatic charge: your projects stay on the PC. To carry on, take out the subscription whenever you like.

Pricing

Sapius, per workstationFirst monthFrom the second month
Businesses and professionals€149 + VAT€299 + VAT per month
Private customers in Italy€181.78 including VAT€364.78 including VAT per month

The promotional first month applies to the account’s first paid activation. The subscription includes all the Sapius tools, Officina, updates and €10 of AI balance for each month and workstation paid for. You can always use your own account, your own API or local AI. Manufacturers’ software and licences are bought from the manufacturers themselves.

Purchases and renewals

In your account area open Acquisti (Purchases), choose Sapius and pay on Stripe: the summary shows the amount and the VAT according to your billing details. Once payment is confirmed, the licence is on the Licenze (Licences) page. Abbonamenti (Subscriptions) and Fatture (Invoices) hold your documents and the management of your account.

The subscription renews every month. You can cancel it whenever you like from your account area, and it stays active until the end of the paid period. Payment management is where you update your payment method. The electronic invoice is sent separately through the Italian SDI. If you buy as a private customer you have 14 days to withdraw: the button is on the Acquisti page, and the form is on the Modulo di recesso (withdrawal form) page.

Workstation licence

The account panel and /licenza show the 24-character machine code. On the Licenze page of your account area, paste the code, activate the workstation and download the .licenza file; then load it into Sapius from the account panel (Load license) or with /licenza <file> in the terminal.

The code identifies the PC: it comes from the motherboard or from the Windows installation, which is why Sapius also works in a virtual machine. If you reinstall Windows, cancel the old activation on the Licenze page and activate the new code. For several cloned virtual machines, give each one its own Windows installation before activating it.

You can move the licence to another PC up to three times in 12 months; downloading the same licence again does not count as a move. Your projects always stay on the PC.

4. AI, balance and budget

Four ways to use AI

  • Your own AI account: you connect ChatGPT and work with the models in your catalogue.
  • Your own compatible API: you enter the model and endpoint and work with your provider.
  • Sapius-managed AI: you use the balance included in the subscription and your top-ups; models and rates are in the catalogue.
  • Local AI: the model runs on your PC and uses neither API nor balance.

The Sapius tools are the same in all four cases. Your choice applies from new conversations onwards: those already open keep their model, connection and billing profile.

With your own account or API, the content needed for the work goes to the provider you chose. With Sapius-managed AI it passes through the Sapius gateway to the provider shown in the catalogue. With local AI it is processed on your PC. Shared knowledge is a separate matter: consent to sharing technical lessons does not cover chats or projects. See the privacy notice and the terms.

Setting up AI

  1. Open Settings → AI and usage.
  2. Choose your ChatGPT account, your own API, Sapius-managed AI or local AI.
  3. With Sapius-managed AI, choose a model from the catalogue and the maximum budget in euros for the work. For your own API, enter the model, a compatible Responses endpoint and the name of the environment variable that holds the key: the secret stays outside Sapius. A local endpoint without authentication can do without the variable.
  4. In the portal, open AI e saldo (AI and balance) to see availability, included and purchased balance, reservations, transactions and rates.

For new conversations with Sapius-managed AI or a compatible API we recommend GPT 6.1 Sol (gpt-6.1-sol), with its five intensity levels: low, medium, high, xhigh and max. With your own account you will find the models in its catalogue.

Balance, top-ups and budget

Every paid month includes €10 of AI balance per workstation, to be used within the period shown in the portal. Optional top-ups come in €20, €50 and €100 + VAT (for private customers in Italy €24.40, €61.00 and €122.00 including VAT): they do not renew automatically and stay available when the month changes. Stripe shows the total before you pay. The rates for each model are on the AI e saldo page, broken down by input, cache and output; you are billed for actual usage.

When the balance or budget limit is reached, the work pauses and keeps its results: you decide whether to raise the limit, top up or change mode. No top-up and no change of model ever starts by itself. To change the limit of a conversation that is already open, press the budget button next to the intensity when the work is paused or finished: the new limit also includes what has already been used.

Local AI

Open AI settings → Install local AI → Install and start, then choose local AI for a new conversation. You need Windows x64, at least 16 GB of installed RAM, 8 GB of it free, and 8 GB of disk space. The model, about 2.76 GB, downloads on first start and runs on your PC’s CPU.

5. Your first project

Creating the project

Press New project, enter the name, customer and revision, and open a conversation. Write down the purpose and constraints of the work. Choose the project’s engineering profile: Siemens, Rockwell, Schneider Machine Expert or Control Expert, CODESYS or Beckhoff.

Choosing the folder

Open the three dots beside the project title, then Project folder. You browse the PC’s folders without typing the path. Confirm the revision; Refresh imports the files that have changed. Imported files are copied into the Sapius project, with their source and revision.

Importing documents into the sources

From the same three dots, open Sources → Import. In the standard file picker, select one or more files and open them. Sapius uses the project’s current revision, gives a result for each file and recognises those already imported, without duplicating sources.

Sources stay in the project with their origin and revision and are available in every conversation of the project, including after a restart. They are distinct from message attachments, which you add with the + in the composer.

You can import up to 20 MB per file: PDF, Word .docx, Excel .xlsx/.xlsm, Markdown, CSV, XML, JSON, text and PLC sources. The summary shows the result file by file. For a scanned PDF, prepare a version with selectable text: Sapius keeps the original among the sources all the same.

PLC / Communication

In the project panel open PLC / Communication. Choose the brand or environment, the family or model, and the protocol. In the second step set the parameters: S7 uses host, port, rack and slot; Modbus TCP uses Unit ID, address base and word order; OPC UA uses URL and security; EtherNet/IP uses CIP family and path. Confirm saves the configuration for future starts; Cancel leaves everything as it was.

The engineering connection to the project and the communication with the PLC have separate statuses: you can change the brand and leave the protocol as it is, and vice versa.

Testing communication

Press Test for an immediate check. S7 checks the protocol negotiation. For Modbus TCP, OPC UA and EtherNet/IP you enter the address or tag and the type to read. The test only reads: no value is written, no command is sent to the CPU. Once you have the result, press Confirm to save the configuration.

OPC UA keeps its certificate checks; the graphical form configures anonymous access.

6. Working with the agent

Conversations and panels

Write the result you want, attach the sources with + and leave the read, edit and verify cycle to the agent. Choose the job intensity in the bar. The log shows the activities; Close or Esc closes the panels. Sign out lets you change account.

While Sapius works, the chat shows updates and activities with icons and expandable details, separate from the final answer, and the plan when the engine reports it. Scrolling follows the work when you are near the bottom; if you scroll up to read, it keeps your position, and Latest updates brings you back to the present. The final answer uses Markdown for lists, code and links.

Enter sends the message; Shift+Enter starts a new line. Ctrl+Enter also sends. If the agent is working, the message joins the queue, as described below; Stop is the separate command for stopping the turn.

To attach, use +, drag a file into the composer or paste a screenshot. Each attachment can be up to 25 MB. Wait for the upload to finish before sending; remove an attachment from the next message with the cross on its card.

Click an attachment or an artefact to open its preview: images and PDFs are shown in the panel; text and source files, including Markdown, are read as text. You open other formats from the project folder. You can widen the panel, drag its edge or close it; in narrow windows it opens over the chat and also closes with Esc.

The i button opens the information panel and Appearance: here you choose the theme (light, dark or match Windows), remembered on the workstation. The ··· menu beside the project title opens its options, the folder and PLC communication.

Queue and Redirect

You can send more messages while the agent is working: they wait in the conversation’s queue and are handled in order. Redirect sends your clarification to the turn in progress, without restarting it: use it to correct an assumption or add a constraint. The approvals stay as you set them.

After a Stop, an error or a restart, the queue stays paused, ready for you: check it and resume. A send with an uncertain outcome is never repeated by itself: you decide.

Results and project memory

Artefacts, facts with their source, decisions and open questions stay in the project. A proposed source, a compiled block, a simulation test and a field verification are different results, and Sapius keeps them distinct: always ask for the compilation result and the tests carried out, together with the file.

The agent can propose how to organise the parameter DBs, the block calls, the diagnostics or a test plan suited to the context. The choices you have already made remain the reference.

Shared knowledge

On first launch or in the settings you can opt in to sharing structured general technical lessons. With the opt-in active, Sapius sends them for review by the owner, who decides on publication. Chats, documents, sources and project data stay out.

Free-text drafts ask for your confirmation every time. You can withdraw your opt-in from the settings whenever you like. Personal preferences, project facts and shared lessons remain three separate memories.

After a correction, Sapius links the error, the change and the successful check, and records the symptom, proposed cause, solution and conditions of applicability. Search also recognises Italian and English technical synonyms, and feedback from reuse helps to assess the lessons.

7. Approvals, All mode and Officina

Consent in the service

The service checks permissions at the moment it runs the tool: you decide, and only you. Analysis, file writes, offline engineering, imports into the project and reads from the PLC are separate operations, and each one keeps its parameters, result and provenance.

Choosing the mode

  • Manual: asks for consent for every operation beyond pure analysis.
  • File changes: allows working files, offline engineering and local commands; asks for the classes that follow.
  • Automatic: also covers reads from the PLC on the declared destination.
  • All: covers TIA imports into the working copy, including FBs, FCs, new DBs, UDTs and Main, without a click for each block. The service records the consent for each attempt and its content.
  • Officina: one consent on an FB or FC covers the corrections to that block for eight hours, in the same copy and CPU; other blocks follow their own approval.

Copies, checks and resuming

All mode works on the copy: the original stays as it is, and downloads and operations on the PLC stay in your hands. The copy checks, the archives and the protections remain active. Replacing an existing DB follows a dedicated path: analysis, isolated copy, compilation and verification.

When a consent is requested, check the destination and the parameters. A refusal is recorded too. On resuming, an operation with an uncertain outcome waits for your decision. Local commands can use the PC’s files and resources: choose the mode according to the work you want to hand over.

8. TIA Portal and other environments

Preparing and connecting TIA

Set the TIA version and the folder for working copies. The agent prepares the copy by archiving and reopening, then identifies the session and path before connecting. Use the project’s own version, so you avoid unintended conversions. When TIA shows the Openness consent prompt, accept it in the Siemens application; TIA may ask for it again after an update.

Program and hardware

Sapius explores CPUs, blocks, tag tables and the hardware configuration, and works on the copy. It writes and imports SCL and SimaticML, organises FBs, FCs, DBs and UDTs, calls the work from Main, compiles, reads the errors, corrects and saves, down to zero errors. To add a module it checks the catalogue, compatibility and the existing configuration.

In All mode, the cycle continues under the consent you have already given for the copy. For existing DBs, Sapius analyses the effects, tries the replacement on an isolated copy and keeps the evidence before adoption. Know-how-protected blocks and the safety program stay as they are.

WinCC and PLCSIM

The WinCC HMI tools work inside TIA on screens, tags and text lists, always on the copy; templates can be inventoried and exported. If the panel uses an integrated connection, you will find it in the tags even when the Connections list is empty: there is no need to create another. With PLCSIM Advanced, Sapius tests the program on a dedicated simulation instance, separate from your working session.

The delivery distinguishes between compilation of the PLC software, the hardware and the HMI. After comparing the exports, Sapius saves and can create a complete archive of the project, with its size and SHA-256.

Other PLCs and HMIs

EnvironmentWhat Sapius does and how you carry on
Rockwell / Studio 5000Reads L5X exports, inventories them and generates or edits ST routines, tags and data types on a copy. You import the file into Studio 5000 and compile there.
CODESYS / Schneider Machine ExpertGenerates ST sources and visualisations (Visualization XML) from a specification, with a catalogue of nine components, and reads exports. You import the files into your CODESYS or Machine Expert IDE.
Schneider Control ExpertGenerates and validates ST sections .XST and new variables .XSY, using an export of your project as a template if you wish. In Control Expert you import the variables first and then the section, analyse and build; if the IDE reports errors, you pass them back to Sapius and it corrects them.
Beckhoff TwinCATReads PLC projects and objects and edits the POUs in ST on a copy, with an archive. You open the copy in XAE to build and activate.
Weintek EasyBuilder ProGenerates the tag CSVs and the typed GetData/SetData macros from a specification, ready to import into EasyBuilder Pro.
FactoryTalk OptixGenerates C# NetLogic and YAML nodes for panels, variables and widgets, including in a copy of the project. You open the project in FactoryTalk Optix and call the Build method.

For every brand, Sapius checks the format of the files it produces and always works on copies: the original stays as it is. To import and compile you use the manufacturer’s software, with its licences.

Finishing the work

Ask for a delivery with files, compilation result, tests and open points. The move to the final project and to the PLC is your decision: you copy the block in TIA from one project to the other, or import the source, which stays among the project’s files.

9. The terminal

Start sapius; sapius --aiuto lists the options. The terminal shares projects, sources and checks with the window. Here the agent uses your own API: pass the key with OPENAI_API_KEY or ANTHROPIC_API_KEY.

/progetti, /nuovo, /conversazioni, /nuova, /fonti and /importa manage the work. /costruttore selects the engineering profile. /plc shows the communication; /plc configura file.json saves it, /plc test file.json [indirizzo tipo] runs a test and /plc rimuovi removes it. /cpu remains available for S7.

/accedi esci signs the account out; /licenza, /prova, /aggiornamenti, /registro, /riprendi and /aiuto complete the main commands. When a consent is requested, an explicit answer from you is needed: closing the terminal does not count as a yes.

10. If something goes wrong

Sign-in, quota and updates

First check which Sapius account and which AI account are connected. If your OpenAI account’s quota is used up, check your OpenAI account or switch to another AI connection in the settings. If the licence is missing, activate it from your account area. If an update does not appear, check your connection and run the update check.

PLC or TIA connection

Check the brand, protocol, destination and parameters. For S7, check the rack, slot and access configuration: PUT/GET and standard-access DBs are needed for S7 reads. For the other protocols, check the test address, the type and the security settings. For TIA, check the version, the Openness group and any dialog boxes waiting for an answer.

Resuming work

Close the panels with Close or Esc. After a Stop, reopen the conversation, check the queue and resume. For an operation with an uncertain outcome, check the log and the destination, then decide whether to repeat it. If you need a hand, write to support@sapiusportal.it: a PLC programmer will answer you.

11. Glossary

Project: a job with its sources, revisions and decisions. Artefact: a file produced and kept. Working copy: the copy of the project that Sapius writes to. Protocol: communication with the device, chosen separately from the IDE. Sample: a value read from the PLC, with quality, time and provenance. Compiled: accepted by the compiler. Simulated: run in a simulation environment. Field verified: checked on the plant, with evidence. Officina: the mode in which one consent covers corrections to the same block for eight hours. Managed AI: AI supplied by Sapius, paid from your balance.