DEV Community: Aiepco

Thuê ngoài lập trình PLC: 6 tài liệu bạn nên yêu cầu trước khi nghiệm thu

Aiepco — Mon, 12 Oct 2026 01:56:15 +0000

Khi một dây chuyền dừng vì sự cố, câu hỏi đầu tiên luôn là: chúng ta có bản sao chương trình không, và có ai hiểu nó không?

Rất nhiều nhà máy trả tiền cho một chương trình chạy được — nhưng không nhận được thứ giúp họ tự đứng được sau đó. Dưới đây là 6 tài liệu nên có trong hợp đồng, kèm lý do vì sao từng cái quan trọng.

1. Chương trình gốc (SCL / LAD / FBD) — không chỉ bản trên máy

Là gì: mã nguồn đầy đủ, có thể mở và biên dịch lại trong TIA Portal.

Vì sao quan trọng: nhiều nơi chỉ nhận được "chương trình đang chạy trong PLC". Khi cần sửa một chi tiết, bạn không có gì để sửa ngoài việc đọc trực tiếp từ thiết bị — và mọi thay đổi đều rủi ro hơn.

Nếu thiếu: lần bảo trì tiếp theo bạn phải thuê lại chính người cũ, với giá do họ quyết định.

2. Bảng phân bổ I/O (địa chỉ, tên tượng trưng, ý nghĩa công nghệ, loại tín hiệu)

Là gì: bảng đối chiếu giữa địa chỉ vật lý (ví dụ I0.3) và ý nghĩa thực tế ("cảm biến vị trí xy-lanh kẹp").

Vì sao quan trọng: đây là cuốn từ điển giữa bản vẽ điện và chương trình. Không có nó, mỗi lần tìm một tín hiệu là một lần đoán.

Nếu thiếu: thời gian xử lý sự cố tăng gấp nhiều lần, và phụ thuộc hoàn toàn vào trí nhớ của người viết.

3. Mô tả cấu trúc POU (khối nào làm gì, gọi nhau ra sao)

Là gì: sơ đồ phân cấp các khối chức năng — khối nào điều khiển xy-lanh, khối nào xử lý báo động, khối nào giao tiếp.

Vì sao quan trọng: chương trình PLC không khó vì cú pháp, nó khó vì phải giữ trong đầu hàng chục quan hệ nhân quả. Một sơ đồ khối tốt biến việc đó thành đọc bản đồ.

Nếu thiếu: người mới phải dành vài ngày chỉ để hiểu chương trình được tổ chức thế nào.

4. Nhật ký biên dịch thực tế (compile log)

Là gì: kết quả biên dịch thật từ TIA Portal, kèm danh sách cảnh báo và cách xử lý từng cảnh báo.

Vì sao quan trọng: "không có lỗi" và "có biên dịch được hay không" là hai chuyện khác nhau. Nhật ký là bằng chứng cứng, không phải lời hứa.

Nếu thiếu: bạn không có cách nào xác nhận chương trình thực sự biên dịch sạch trước khi lên máy.

5. Báo cáo kiểm tra tĩnh

Là gì: kết quả kiểm tra tự động theo các quy tắc (nguy cơ chia cho 0, truy cập mảng ngoài biên, hằng số không tên, độ sâu lồng nhau, tỉ lệ chú thích…).

Vì sao quan trọng: nó phát hiện được một tầng lỗi — và điều quan trọng không kém là báo cáo phải nói rõ tầng nào nó không kiểm tra được.

⚠ Nhắc nhở trung thực: kiểm tra tĩnh không thấy lỗi ngữ nghĩa. Ví dụ đổi AND thành OR trong điều kiện khởi động — sai hoàn toàn về logic — nhưng mọi công cụ dựa trên văn bản đều không phát hiện. Đừng để ai thuyết phục bạn rằng "đã kiểm tra tĩnh" nghĩa là "logic đúng".

6. Hồ sơ kiểm chứng + danh sách điểm chưa quyết

Là gì: hai phần —

hồ sơ kiểm chứng: đối chiếu quỹ đạo mô phỏng, kiểm tra chuyển trạng thái và thời gian timer;
danh sách điểm chưa quyết: những điều kiện hiện trường chưa xác nhận, mỗi điểm ghi rõ hai nhánh xử lý ("nếu đúng / nếu không đúng").

Vì sao quan trọng: phần thứ hai là thứ hầu như không ai giao. Nó cho bạn biết chương trình đang giả định điều gì về nhà máy của bạn — và nếu giả định đó sai thì điều gì sẽ xảy ra.

Nếu thiếu: bạn nhận một chương trình "chạy được" mà không biết nó phụ thuộc vào những giả định nào.

Cách ghi vào hợp đồng

Ba câu có thể thêm vào mọi hợp đồng thuê ngoài lập trình PLC:

Danh mục bàn giao liệt kê rõ 6 mục trên, kèm định dạng tệp.
Điều kiện nghiệm thu phải viết được phép kiểm chứng: "dây chuyền chạy đúng trình tự nêu ở mục 3.2" tốt hơn nhiều so với "logic chính xác".
Cam kết nêu rõ phần không thuộc phạm vi: thiết kế điện, tủ điện, ký duyệt an toàn chức năng (SIL/PL) — những việc này phải do bên có đủ năng lực thực hiện.

Điểm cuối cùng không phải để đẩy việc đi, mà để tránh hiểu sai ngay từ đầu — nguyên nhân phổ biến nhất khiến công việc kéo dài.

Chúng tôi làm việc thế nào

Chúng tôi phát triển và kiểm chứng chương trình PLC cho Siemens S7-1200 / S7-1500 (SCL, LAD, FBD), và bàn giao cả 6 tài liệu trên như danh mục tiêu chuẩn — không phải dịch vụ cộng thêm.

Chúng tôi cũng nói rõ giới hạn của mình: chỉ làm chương trình và kiểm chứng; không thiết kế điện, không ký thay cho an toàn chức năng.

Chi tiết về quy trình và bằng chứng: plc.aiepco.com/vi/

Bài viết dựa trên quy trình bàn giao thực tế của chúng tôi. Không có thông tin khách hàng nào trong bài.

Taking over someone else's PLC program: do these 4 things before you change a single line

Aiepco — Sun, 11 Oct 2026 06:31:25 +0000

You have just been handed a machine that runs — but nobody can explain it. The previous engineer left, the original documentation is gone, or the system was simply "commissioned in a hurry and never cleaned up".

The most natural move is also the most expensive one: open TIA Portal and start editing.

This is the sequence we use when a customer asks us to rescue or diagnose an inherited program. It is deliberately boring, and it exists because the exciting version fails.

Why you cannot start by fixing

In a program that runs, the "obviously redundant" logic is very likely a patch someone added after an incident. You can see the code; you cannot see the incident.

If you change it without a baseline and without evidence, you do not remove the problem — you replace it with a different one. And the new problem is usually harder to find, because you introduced it yourself. Two weeks later you are back at the starting point, now with a second unknown in the system.

The 4 things, in order

① Capture evidence before you touch anything

Archive everything you can currently get:

the program uploaded from the PLC, as it is right now
the diagnostic buffer
the alarm history
the actual state of the main I/O points
the operator's description of when things go wrong (spoken words are data too)

This is the raw material for every judgement you will make later. Once you start editing, the state of the machine at handover is gone forever. It is the one thing you cannot re-create.

② Establish a version baseline

Save the uploaded program with a dated archive entry and one sentence: "This version was uploaded from the machine on , unmodified."

It feels trivial. It is the only basis on which you will later be able to say what you changed and why — and the only starting point the next person can take over from.

③ Shrink the search space with static analysis and reasoning

Do not guess from the symptom. Run the program through tooling first: division-by-zero risk, array access without bounds checks, block call depth, unused variables, naming inconsistencies. You are not looking for the bug yet — you are trying to convert "one large unknown program" into "four suspicious blocks".

Then list the plausible causes and rank them by likelihood. Resist the urge to work through them in the order they occurred to you.

④ Change only after the root cause is verified

Confirm the root cause in simulation or by single-stepping on site. Then change. Then run a regression pass, because breaking B while fixing A is the normal case, not the exception.

Every change gets the same archive treatment as step ②.

A ratio worth remembering: when taking over an inherited program, about 90% of the time belongs to "understanding what it currently is", and 10% to "making it what I want". Invert that ratio and you will be back at the start in two weeks.

What to ask the other side for

Ask even if the answer is "we don't have it" — a "no" is itself information about how the system has been maintained.

A program backup. Any version, the older the better — old versions are what you compare against.
PLC model and firmware version (the order number is the accurate one).
I/O list or electrical drawings — even a draft.
Which faults have occurred historically, and what was done about them.
Who knows why a particular piece of logic is written the way it is. That person is worth more than any document.

Scope note (what remote work can and cannot cover)

Program-level investigation — uploading, static analysis, logic review, root-cause reasoning — can be done remotely, and that is how we usually start.

What cannot be done remotely: wiring and hardware replacement, capturing real machine traces, and independent verification of safety functions. Those need hands on the machine.

We publish this because we think the boundary should be stated up front rather than discovered in week three.

This is a cross-post. The original article lives at plc.aiepco.com/en/notes/takeover-checklist/, and our full engineering process is documented at plc.aiepco.com/en/process/.

Outsourcing PLC programming: the 6 documents to ask for

Aiepco — Tue, 29 Sep 2026 01:04:25 +0000

Many plants pay for a program that runs — and never receive what they need to maintain it themselves.

When a line stops, the first two questions are always: do we have a copy of the program, and does anyone understand it? The list below exists to answer both. It is not moral advice about suppliers working harder — every item can be written into a contract as an acceptance criterion.

We write PLC programs for a living (Siemens S7-1200/1500). This is what we hand over, and why each piece matters.

1. The program itself (SCL / LAD / FBD)

What it is: complete source you can open and recompile in TIA Portal.

Why it matters: many sites only ever receive "the version currently running in the PLC." If all you hold is what is on the device, every future change becomes an online edit — with multiplied risk and cost.

Without it: the next maintenance job goes to whoever wrote it last, at whatever price they name.

2. I/O allocation table

What it is: a cross-reference between physical addresses (I0.3) and real meaning ("clamp cylinder position sensor") — address, symbolic name, process meaning, signal type.

Why it matters: this is the dictionary between the electrical drawings and the program. Without it, tracing a single signal is guesswork.

Without it: fault-finding takes many times longer and depends entirely on someone's memory.

3. POU structure description

What it is: the hierarchy of function blocks — which block handles a cylinder, which handles alarms, which handles communications, and how they call each other.

Why it matters: PLC programs are not hard because of syntax. They are hard because you must hold dozens of causal relationships in your head at once. A good structure diagram turns that into reading a map.

Without it: a new engineer spends days just working out how the program is organised.

4. Compile log

What it is: the actual compilation output from TIA Portal, plus how each warning was handled.

Why it matters: "no errors" and "does it compile" are two different statements. The log is hard evidence, not a promise.

Without it: you have no way to confirm the program really compiles cleanly before it goes on the machine.

5. Static analysis report

What it is: rule-based automated checks (division-by-zero risk, array bounds, unnamed constants, nesting depth, comment ratio), and an explicit statement of which layer it did not check.

Why it matters: it catches one layer of defects. Equally important is saying which layer it cannot see.

⚠ An honest reminder: static analysis cannot see semantic errors. Flip an AND to OR in a start condition — the logic is now exactly backwards — and no text- or structure-based tool will catch it. Never let "it passed static analysis" be used to imply "the logic is correct."

6. Verification records + the open-items list

What it is: two parts.

Verification records: simulation trace comparisons, state-transition and timer-timing checks.
Open-items list: the site conditions that were never confirmed, each stating the branch action for both "if yes" and "if no."

Why it matters: that second part is what almost nobody hands over. It tells you which assumptions the program makes about your plant — and what happens if an assumption is wrong.

Without it: you receive a program that "works" without knowing what it depends on.

Put these three sentences in the contract

Deliverables list — enumerate the six items above, with file formats.
Acceptance criteria — write them as verifiable assertions. "Executes the sequence in section 3.2 correctly, 10 consecutive runs" beats "logic is correct."
Scope statement — state what is out of scope: electrical design, switchgear assembly, and functional safety (SIL/PL) sign-off must be done by a qualified party.

That last one is not about pushing work away — it is about avoiding the misunderstanding that, in our experience, is the single most common reason a job drags on.

We develop and verify Siemens S7-1200/1500 PLC programs — and we hand over all six documents above as part of the standard scope, not as an add-on. How we work: plc.aiepco.com

A linter that silently passes is worse than no linter at all

Aiepco — Mon, 28 Sep 2026 08:43:36 +0000

Our static analyzer had been reporting no issues found on our PLC codebase for months.

Then we built a fixture stuffed with deliberate bugs — and found that two of its rules had never fired on a single line of code. Not once, since the day they were written.

This is a post-mortem of our own verification toolchain failing, and the eight checks we now run before we trust any checker.

Context: what we verify, and why it matters

We develop and verify Siemens S7-1200/1500 PLC programs (SCL, IEC 61131-3). The code runs production lines. A defect is not a bad user experience — it's a stopped line, scrapped product, or a safety incident.

So we built a verification chain: static analysis rules, a self-test suite, and mutation testing. This article is about that toolchain failing at its job.

Finding #1 — a rule that could never fire

Here is what a normal run looked like:

[motor_control_ref.scl]
  LOC=86 SLOC=61 comment_rate=27% McCabe≈9 nesting=3 magic_numbers=0
  POU: FUNCTION_BLOCK FB200_MotorControl (line 11)
  No static issues found

One green line. Looks like good news.

Meanwhile we were writing a fixture — a file full of deliberately planted defects — to check whether the rules actually work. The result was unsettling: the fixture contained #m_rB used as a divisor, and unguarded array access like #m_Buffer[#i_Index]. The rules for division-by-zero risk and array-out-of-bounds risk reported nothing.

The cause was in the regex:

/(?![/\\*])\s*([A-Za-z_][A-Za-z0-9_]*)

It looks for a variable name following a slash. But SCL local variables carry a # prefix — the real code is #m_rA / #m_rB. After the slash comes a space, then #, then the name. The # broke the match.

Two rules, written months earlier, had never matched anything.

Finding #2 — the scary part is its siblings

Fixing the regex took five minutes. The whole next day went into a different question: how many other rules are like this?

We ran every rule against the fixture. Three more problems surfaced:

Problem	Symptom	Nature
`VAR CONSTANT` treated as a static variable	All 6 constants flagged with "non-standard naming prefix"	False positive — rule too broad
Safety-comment check too aggressive	One function block produced 17 warnings of the same kind	Noise flood — real issues get buried
Call-graph parsed `ELSIF (...)` as an FB call	Call-depth analysis distorted	Misparse — parser boundary error

Three rules, three different diseases: too broad, too noisy, misparsed. Together with the two that never fired, that's five failure modes.

The common property: none of them raised an error. The tool didn't crash, didn't throw, didn't warn. It just quietly produced a wrong conclusion.

Finding #3 — "passes" is not one thing

We then ran mutation testing: inject a defect into clean code and see whether the chain catches it. Twelve mutation classes:

Syntax / structural (missing END_IF, missing semicolon, unbalanced parentheses, naming violations, magic numbers, stripped comments) → caught 6/6 by static analysis.
Semantic (AND → OR, deleted NOT, inverted comparison, altered initial value, removed interlock) → caught 0/6.

The most instructive number: we flipped the AND in a start condition to OR — the logic is now exactly backwards — and compared the text against the reference implementation:

BLEU-4 cumulative : 0.9981
Line-level match  : 97.6%

Nearly a perfect score. Semantic mutations can make code look more like the reference, not less. No text- or structure-based tool can see them.

So we put that limitation into the report rather than tuning the numbers:

Static analysis passing ≠ compiling ≠ being logically correct.
Semantic correctness is the job of dynamic verification (simulation, on-machine trace comparison) and human review.

Finding #4 — the docs referenced scripts that didn't exist

One more, and it is embarrassing rather than interesting: our framework documentation listed a set of tooling scripts. At that moment, none of them existed yet. The documentation was complete; the implementation was zero.

Same disease: interface declarations divorced from implementations. We added an assertion that scans the docs and fails if any referenced script or template is missing. Dead links don't get a second chance.

What we changed

Three rules, all cheap:

Every rule needs a fixture that must trigger it. Write the rule, immediately build a sample containing that defect, assert it is reported. Freeze the sample as a regression test.
Every rule needs a counter-fixture that must not trigger it. Run it against compliant code, assert zero warnings. Without this you get the worse failure: the team learns to ignore all warnings, which is identical to having no checker.
The toolchain must prove itself first. Ours is 45 self-test assertions, a few seconds to run:

$ selftest_tools.py
assertions 45, failures 0
result: OK — toolchain behaves as declared

The rule is blunt: if the toolchain self-test isn't fully green, you may not use it to judge code. An unverified tool's "pass" is not evidence.

The eight checks we now apply to any checker

Abstracted, this is a checklist you can run against your own linters, analyzers or CI gates:

Does every rule have a sample that must trigger it? (No → you don't know whether it runs at all.)
Does every rule have a counter-sample that must not trigger it? (No → it may be killing valid code.)
Is the warning count sane? 17 identical warnings in one file means the rule is noise, and the team will ignore it.
When the tool fails, does it error or does it go silent? Silent failure is the dangerous kind.
Is there a meta-test guarding the tool itself? Changing A and breaking B is the norm, not the exception.
Have you written down what the tool deliberately does not do? Unstated boundaries are read as omniscience.
Does every file referenced in the documentation actually exist?
Before the word "passed", is there a line saying which layer passed?

Why publish this

There's no growth chart or ROI curve here. It's a record of our own toolchain failing and being fixed.

We publish it because of a fairly plain belief: if a supplier won't tell you whether their own checkers have been verified, you should trust what they hand you even less.

We prefer to say three separate sentences — static checks passed / it compiles / the logic is correct — rather than one vague "quality assured". Keeping them separate is more useful to the person paying for the work.

This is a real internal post-mortem. All figures (14 static rules, 45 self-test assertions, 6/6 vs 0/6 mutation detection, BLEU 0.9981) come from actual tool output, and contain no client information.

We develop and verify Siemens S7-1200/1500 PLC programs — and we build the tooling that proves they're correct. How we work: plc.aiepco.com