오류가 났을 때 돌아오는 값
오류는 두 갈래입니다. 이 구분이 가장 중요합니다.
갈래 |
어떻게 보이나 |
예 |
|---|---|---|
가. 답이 오는 오류 |
서버가 |
물체가 없다, 레시피가 없다 |
나. 답이 오지 않는 오류 |
한 줄도 오지 않습니다. 붙지 못하거나, 끊기거나, 기다려도 답이 없습니다 |
서버가 꺼져 있다 |
경고
어느 쪽이든 원칙은 같습니다. 옵셋을 받지 못했으면 로봇을 보정하지 마세요. 앞 측정의 옵셋을 다시 쓰지 마세요.
답이 오는 오류의 모양
답이 오는 오류는 고장이 아니라 정상 응답입니다. 접속은 그대로 살아 있고 다음 주문서를 바로 보낼 수 있습니다.
돌아오는 줄의 모양은 세 가지뿐입니다.
모양 1 — 주문서를 읽지 못했을 때. 값이 2개입니다.
{"ok":false,"errorCode":"BAD_REQUEST"}
모양 2 — 계산까지 가지 못했을 때. 값이 6개입니다. offset 이 없습니다.
{"at":"2026-11-22T03:38:51","source":"upper","recipeId":777,"ok":false,"errorCode":"RECIPE_NOT_FOUND","elapsedMs":0}
모양 3 — 계산은 했는데 기준에 떨어졌을 때. 모양 2 에 품질 값 4개가 더 붙습니다. offset 은 역시 없습니다.
{"at":"2026-11-22T03:46:07","source":"upper","recipeId":5,"ok":false,"errorCode":"OUT_OF_RANGE","inlierShare":1.000,"fitness":1.000,"inlierRmseMm":0.0098,"usedFallback":false,"elapsedMs":343}
세 모양에 들어 있는 값을 표로 보면 이렇습니다.
이름 |
모양 1 |
모양 2 |
모양 3 |
설명 |
|---|---|---|---|---|
|
있음 |
있음 |
있음 |
늘 |
|
있음 |
있음 |
있음 |
오류의 종류. 아래 “오류 코드 9종” |
|
없음 |
있음 |
있음 |
그 요청이 끝난 시각 |
|
없음 |
있음 |
있음 |
늘 |
|
없음 |
있음 |
있음 |
요청한 번호 |
|
없음 |
있음 |
있음 |
서버 안에서 걸린 시간(ms) |
|
없음 |
없음 |
있음 |
얼마나 못 미쳤는지 보는 품질 값. 뜻은 성공했을 때 돌아오는 값와 같습니다 |
|
없음 |
없음 |
없음 |
오류에는 절대 없습니다 |
짤 때 지킬 것은 셋입니다.
ok를 먼저 봅니다.false면offset을 읽으려 하지 않습니다. 없는 값을 읽으면 프로그램이 죽습니다.errorCode말고 다른 값은 없을 수도 있다고 보고 읽습니다. 모양 1 에는at도recipeId도 없습니다.사람에게 보여 줄 설명 문장은 오지 않습니다. 코드만 옵니다. 화면에 띄울 문장은 상위 프로그램이 이 장을 보고 만듭니다.
오류 코드 9종
서버는 아래 순서대로 확인하고, 처음 걸린 것 하나만 돌려줍니다.
순서 |
|
한 줄 뜻 |
모양 |
그대로 다시 보내면 |
|---|---|---|---|---|
1 |
|
주문서를 읽지 못했다 |
1 |
또 같은 오류 |
2 |
|
지금은 측정할 수 없다 |
2 |
상황이 풀리면 됩니다 |
3 |
|
그 번호의 레시피가 없다 |
2 |
또 같은 오류 |
4 |
|
레시피의 레퍼런스 파일을 읽지 못했다 |
2 |
또 같은 오류 |
5 |
|
센서에서 사진을 받지 못했다 |
2 |
센서가 돌아오면 됩니다 |
5 |
|
센서 라이선스가 맞지 않는다 |
2 |
또 같은 오류 |
6 |
|
물체가 찍히지 않았다 |
2 |
물체를 놓으면 됩니다 |
7 |
|
레퍼런스와 잘 겹치지 않는다 |
3 (드물게 2) |
물체 상태가 바뀌어야 됩니다 |
8 |
|
겹쳤지만 너무 많이 어긋났다 |
3 |
물체 자리가 바뀌어야 됩니다 |
아래에 하나씩 적습니다. “돌아오는 줄”은 실제로 받은 것입니다.
BAD_REQUEST — 주문서를 읽지 못했다
언제: 줄이 JSON 이 아닐 때.
cmd가 없거나 모르는 명령일 때.measure인데recipeId가 없거나 따옴표가 붙었을 때(숫자가 아닐 때).할 일: 상위 프로그램이 보내는 줄을 고칩니다. 현장에서 이 오류가 나면 프로그램의 버그입니다. 다시 보내도 소용없습니다.
확인: 서버의
data/logs/Remote/날짜/날짜.txt에서받음줄을 보면 서버가 실제로 받은 글자가 적혀 있습니다.
{"ok":false,"errorCode":"BAD_REQUEST"}
BUSY — 지금은 측정할 수 없다
언제: 둘 가운데 하나입니다. 누군가 설정 화면에서 레시피를 등록하는 중입니다. 또는 화면에서 센서 연결을 해제해 두었습니다.
할 일: 작업자에게 “설정 화면에서 등록을 끝내 달라” 또는 “센서를 다시 연결해 달라”고 알립니다. 그 뒤 다시 보냅니다.
참고: 곧바로(0 ms) 돌아옵니다. 쉬지 않고 연달아 다시 보내지 마세요. 몇 초 간격을 둡니다.
{"at":"2026-11-22T03:39:15","source":"upper","recipeId":5,"ok":false,"errorCode":"BUSY","elapsedMs":0}
RECIPE_NOT_FOUND — 그 번호의 레시피가 없다
언제: 그 번호로 등록된 레시피가 없습니다. 레시피 번호는 1~99 입니다. 그 밖의 숫자(0, 100, 1.5, -1,
1e999)도 이 오류로 답합니다.할 일:
recipes명령으로 있는 번호를 확인합니다. 번호가 맞다면 설정 화면에서 그 레시피를 등록합니다.
{"at":"2026-11-22T03:38:51","source":"upper","recipeId":777,"ok":false,"errorCode":"RECIPE_NOT_FOUND","elapsedMs":0}
INTERNAL — 레퍼런스 파일을 읽지 못했다
언제: 레시피 목록에는 있는데 그 레퍼런스 파일(
data/recipes/번호.pcd)이 없거나 깨졌습니다.할 일: 그 레시피를 설정 화면에서 다시 등록합니다. 상위 프로그램이 고칠 수 있는 오류가 아닙니다.
{"at":"2026-11-22T03:45:00","source":"upper","recipeId":7,"ok":false,"errorCode":"INTERNAL","elapsedMs":0}
SENSOR_OFFLINE — 센서에서 사진을 받지 못했다
언제: 센서 케이블이 빠졌습니다. 센서 전원이 꺼졌습니다. 다른 프로그램(LJ-S Navigator 등)이 센서를 쥐고 있습니다.
할 일: 작업자에게 센서 점검을 알립니다. 서버는 5초마다 스스로 센서에 다시 붙습니다. 몇 초 뒤 다시 보내 보세요.
참고: 이 답이 오기까지 얼마나 걸리는지는 재지 못했습니다. 정상 측정보다 길 수 있습니다.
{"at":"…","source":"upper","recipeId":5,"ok":false,"errorCode":"SENSOR_OFFLINE","elapsedMs":…}
참고
이 줄만 실제로 받은 것이 아닙니다. 코드에서 읽은 모양입니다. LICENSE_INVALID 와 같은 자리에서 만들어지므로 모양은 같습니다.
LICENSE_INVALID — 센서 라이선스가 맞지 않는다
언제: 라이선스 파일이 없습니다. 또는 다른 센서용 파일입니다. 서버는 라이선스에 적힌 센서에 붙었을 때만 찍습니다.
할 일: 설정 화면의 시스템 설정 → 라이선스 탭에서 맞는 파일을 등록합니다. 등록하기 전에는 다시 보내도 같습니다.
{"at":"2026-11-22T03:26:48","source":"upper","recipeId":1,"ok":false,"errorCode":"LICENSE_INVALID","elapsedMs":1009}
NO_OBJECT — 물체가 찍히지 않았다
언제: 찍힌 점이 너무 적습니다(기준 1000점). 물체가 아예 없거나, 관심 영역 상자 밖에 놓였습니다.
할 일: 물체가 센서 아래 제자리에 있는지 확인합니다. 물체 공급 쪽 문제일 가능성이 큽니다.
{"at":"2026-11-22T03:44:30","source":"upper","recipeId":6,"ok":false,"errorCode":"NO_OBJECT","elapsedMs":318}
LOW_QUALITY — 레퍼런스와 잘 겹치지 않는다
언제: 겹쳐 보았는데 겹침 비율이나
fitness가 기준(겹침 비율 0.85,fitness0.90)에 못 미칩니다. 다른 종류의 물체입니다. 뒤집혔거나 많이 틀어졌습니다. 일부가 가려졌습니다. 레시피 번호를 잘못 골랐습니다.할 일: 물체와 레시피 번호를 확인합니다.
inlierShare와fitness를 기록해 두세요. 기준에 아슬아슬하게 떨어진 것인지 전혀 다른 물체인지 가릴 수 있습니다.참고: 계산 자체가 실패하면 품질 값 없이 모양 2 로 올 수도 있습니다. 품질 값은 “있으면 읽는다”로 짭니다.
{"at":"2026-11-22T03:38:47","source":"upper","recipeId":1,"ok":false,"errorCode":"LOW_QUALITY","inlierShare":0.000,"fitness":0.000,"inlierRmseMm":0.0000,"usedFallback":false,"elapsedMs":450}
OUT_OF_RANGE — 겹쳤지만 너무 많이 어긋났다
언제: 잘 겹치기는 했습니다. 그런데 어긋난 양이 한도(이동 5 mm, 회전 5 도)를 넘습니다.
할 일: 물체가 놓인 자리를 확인합니다. 물체는 맞는데 자리가 많이 벗어났다는 뜻입니다.
{"at":"2026-11-22T03:46:07","source":"upper","recipeId":5,"ok":false,"errorCode":"OUT_OF_RANGE","inlierShare":1.000,"fitness":1.000,"inlierRmseMm":0.0098,"usedFallback":false,"elapsedMs":343}
이 줄은 한도를 일부러 아주 작게 낮춰 놓고 받은 것입니다.
경고
얼마나 어긋났는지는 알려 주지 않습니다. 이 오류에는 offset 이 없습니다.
한도를 넘는 값으로 로봇을 움직이지 않게 하려는 것입니다.
기준 값과 모르는 코드
위의 기준 값(1000점, 0.85, 0.90, 5 mm, 5 도)은 서버의 data/config.json 에 있는 임시 값입니다.
경고
모르는 코드가 오면 오류로 다루세요. 코드는 늘어날 수 있습니다.
설계에는 ROBOT_OFFLINE, ROBOT_MOVED, NOT_CALIBRATED 가 있지만 이번 판에서는 나오지 않습니다.
“아는 코드가 아니면 성공”이 아니라 “ok 가 true 가 아니면 실패”로 짜세요.
답이 오지 않는 오류
이 경우에는 errorCode 가 없습니다. JSON 이 아예 오지 않습니다. 프로그래밍 언어가 내는 오류(예외)나 제한 시간으로 알아챕니다.
겪는 일 |
까닭 |
할 일 |
|---|---|---|
붙을 때 “연결이 거부됨” 오류가 납니다 |
서버가 꺼져 있습니다. 포트 번호가 다릅니다. 다른 PC 에서 붙으려 했습니다 |
서버 명령 창이 떠 있는지, 거기 찍힌 포트가 맞는지 봅니다. 몇 초 뒤 다시 붙습니다 |
받기가 “0 글자”로 끝나거나 보내기에서 오류가 납니다 |
서버가 꺼졌습니다. 또는 줄 바꿈 없이 65536 바이트 넘게 보내 서버가 끊었습니다 |
접속을 닫고 다시 붙습니다 |
보냈는데 아무리 기다려도 답이 없습니다 |
줄 끝의 줄 바꿈을 빠뜨렸습니다. 또는 측정이 오래 걸리고 있습니다 |
줄 바꿈을 확인합니다. 제한 시간을 넘기면 접속을 닫고 다시 붙습니다 (시간과 순서) |
큰 숫자를 보낸 직후 접속이 끊기고 다시 붙지도 못합니다 |
서버가 죽었습니다 (조심할 것과 바뀔 수 있는 것의 알려진 문제) |
서버를 다시 띄웁니다. 보내는 값을 고칩니다 |
오류를 다루는 순서
답을 받았는가?
├─ 아니오 → 접속을 닫는다. 옵셋 없음. 다시 붙어서 시도하거나 작업자에게 알린다.
└─ 예 → ok 가 true 인가?
├─ 예 → offset 을 쓴다.
└─ 아니오 → 옵셋 없음. errorCode 를 본다.
├─ BUSY, SENSOR_OFFLINE → 몇 초 뒤 다시 보낸다. 횟수를 정해 둔다.
├─ NO_OBJECT, LOW_QUALITY, OUT_OF_RANGE → 물체 문제. 셀의 규칙대로 처리한다(배출, 정지, 작업자 호출).
└─ 그 밖 (모르는 코드 포함) → 다시 보내도 같다. 멈추고 작업자를 부른다.