roboception
diff --git a/‎FANUC/README_FANUC.md‎
Lines changed: 55 additions & 25 deletions b/‎FANUC/README_FANUC.md‎
Lines changed: 55 additions & 25 deletions
diff --git a/‎FANUC/TP/GRI_EXAMPLE_ASYNC.LS‎
Lines changed: 58 additions & 0 deletions b/‎FANUC/TP/GRI_EXAMPLE_ASYNC.LS‎
Lines changed: 58 additions & 0 deletions
diff --git a/‎FANUC/TP/GRI_EXAMPLE_HEC.LS‎
Lines changed: 60 additions & 72 deletions b/‎FANUC/TP/GRI_EXAMPLE_HEC.LS‎
Lines changed: 60 additions & 72 deletions
@@ -6,6 +6,8 @@ This document describes the FANUC client implementation for Roboception's Generi
 
 The FANUC GRI client provides a straightforward way to integrate Roboception vision capabilities into your FANUC robot programs. Instead of complex register manipulation, you can access vision functions through simple CALL statements and status checks.
 
+**This integration uses the GRI protocol version defined by Roboception firmware 25.10 and later**
+
 ### Key Features
 
 - **Vision Job Execution**: Trigger synchronous and asynchronous vision jobs
@@ -40,6 +42,7 @@ Load the following files onto your FANUC robot controller:
 
 **TP Programs** (load .ls files):
 - `GRI_OPEN_COMMUNICATION.LS` - System initialization
+- `GRI_SETFRAMES.LS` - Utility to standardize frames (sets `UF:0` world and `UT:0` flange)
 - `GRI_TRIGGER_JOB_SYNC.LS` - Execute vision job (blocking)
 - `GRI_TRIGGER_JOB_ASYNC.LS` - Execute vision job (non-blocking)
 - `GRI_GET_JOB_STATUS.LS` - Check async job status
@@ -100,7 +103,7 @@ Optional example programs (load .ls files):
 - `R[143]` `gri param 1`: slot id (HEC_SET_POSE)
 - `R[144]` `gri param 2`: reserved
 
-**Status Registers (KAREL → TP) - New uniform mapping:**
+**Status Registers (KAREL → TP) - Uniform mapping:**
 - `R[149]` `gri comm status`: handshake; 0 ready, -1 stopped
 - `R[150]` `gri error code`: signed GRI status (<0 error, 0 ok, >0 warning)
 - `R[151]` `module return`: `data_1` (module/vendor code; can be <0/0/>0)
@@ -115,19 +118,32 @@ Optional example programs (load .ls files):
 - Notes on `R[150]/R[151]`
   - Pose-returning calls (`GRI_TRIGGER_JOB_SYNC`, `GRI_GET_NEXT_GRASP`, `GRI_GET_RELATED_GRASP`):
     - On success: `R[150] = 0`; pose in `PR[53]`; counts in `R[152]/R[153]`
-    - No poses: `R[150] = 1`
-    - Errors: `R[150] < 0` (e.g., `-4` API_RESPONSE_ERROR; raw cause may be in `R[151]`)
-  - Confirmation calls (`GRI_TRIGGER_JOB_ASYNC`, `GRI_HEC_*`): `R[150] = 0` on success; otherwise `<0` error, with detail possibly in `R[151]`
+    - No poses: `R[150] = 1` (NO_POSES_FOUND)
+    - Errors: `R[150] < 0` (e.g., `-4` API_RESPONSE_ERROR; raw in `R[151]`)
+  - Confirmation calls (`GRI_TRIGGER_JOB_ASYNC`, `GRI_HEC_*`): `R[150] = 0` on success; on failure `R[150] < 0` with module/vendor detail in `R[151]`
   - Status call (`GRI_GET_JOB_STATUS`): `R[150] = 0` on success; `R[152] = 1|2|3|4` → INACTIVE|RUNNING|DONE|FAILED
 
 
 
+### Frame Convention
+
+- KAREL always exchanges poses on the wire as world/base → flange (mm/deg).
+- All LS examples standardize frames at program start by calling:
+  - `CALL GRI_SETFRAMES` (sets `UF:0` world and `UT:0` flange)
+- Tool 0 must be the identity (flange). If Tool 0 was modified, correct it or transform poses accordingly.
+
+Changing the convention (advanced):
+- If you must use a different UF/UT, update `FANUC/TP/GRI_SETFRAMES.LS` accordingly, or manage frames yourself and remove the helper call from your program.
+- Alternatively, keep world→flange in `PR[53]` and transform it to your chosen UF before moving.
+
 ### Simple Vision-Guided Picking
 
 ```fanuc
 /PROG VISION_PICK_EXAMPLE
 /MN
-  ! Start vision system
+  ! Standardize frames: UF:0 (world), UT:0 (flange)
+  CALL GRI_SETFRAMES ;
+  ! Start GRI communication
   CALL GRI_OPEN_COMMUNICATION ;
   
   ! Execute vision job
@@ -139,7 +155,9 @@ Optional example programs (load .ls files):
   JMP LBL[cleanup] ;
   
   LBL[pick_object] ;
-  ! Move to detected pose (in PR[53])
+  ! Move to detected pose (in PR[53]) using world/base and flange
+  UFRAME_NUM=0 ;
+  UTOOL_NUM=0 ;
   L PR[53:gri pose] 200mm/sec FINE ;
   ! Execute gripper close
   DO[1:Gripper]=ON ;
@@ -154,7 +172,6 @@ Optional example programs (load .ls files):
 ```fanuc
 /PROG PROCESS_MULTIPLE_OBJECTS
 /MN
-  CALL GRI_OPEN_COMMUNICATION ;
   
   ! Process objects until none remain
   LBL[next_object] ;
@@ -183,7 +200,7 @@ Optional example programs (load .ls files):
 ### Asynchronous Processing
 
 ```fanuc
-! Start vision job in background
+! Start background job
 CALL GRI_TRIGGER_JOB_ASYNC(1) ;
 IF R[150:gri error code]<>0, JMP LBL[async_failed] ;
 
@@ -193,13 +210,15 @@ CALL OTHER_ROBOT_OPERATIONS ;
 ! Poll job status until done
 LBL[poll] ;
 CALL GRI_GET_JOB_STATUS(1) ;
-IF R[152:gri data 1]=2, JMP LBL[poll] ;      -- RUNNING
-IF R[152:gri data 1]<>3, JMP LBL[async_failed] ; -- not DONE
+IF R[152:data 2]=2, JMP LBL[poll] ;      -- RUNNING
+IF R[152:data 2]<>3, JMP LBL[async_failed] ; -- not DONE
 
 ! Job is DONE → fetch results
 LBL[next] ;
 CALL GRI_GET_NEXT_GRASP(1) ;
 IF R[150:gri error code]<>0, JMP LBL[finished] ;
+UFRAME_NUM=0 ;
+UTOOL_NUM=0 ;
 L PR[53:gri pose] 150mm/sec FINE ;
 IF R[152:gri data 1]>0, JMP LBL[next] ;
 LBL[finished] ;
@@ -212,7 +231,13 @@ LBL[after] ;
 
 ## Status Codes
 
-R[150] carries signed status: `<0` error, `0` ok, `>0` warning. For pose-returning calls, success (`0`) means a pose is available in `PR[53]`. For job status (`GRI_GET_JOB_STATUS`), `R[150]=0` on success and the job state is in `R[152]` (1..4).
+`R[150]` semantics are uniform across functions:
+
+- `R[150] = 0`: success
+- `R[150] < 0`: error (see `R[151]` for module/vendor detail)
+- `R[150] > 0`: warning/non-fatal (e.g., `1` = NO_POSES_FOUND)
+
+For job status (`GRI_GET_JOB_STATUS`): `R[150] = 0` on success and `R[152] ∈ {1,2,3,4}` → INACTIVE|RUNNING|DONE|FAILED.
 
 ## Hand-Eye Calibration
 
@@ -296,7 +321,7 @@ CALL GRI_QUIT ;
 
 ### No Objects Detected
 
-- If the pose-returning call does not find a pose, `R[150]` will be `23` and `R[151] = 13` (no poses found). Check scene and job configuration.
+- If the pose-returning call does not find a pose, `R[150]` will be `1` (NO_POSES_FOUND). Check scene and job configuration.
 - Check scene lighting and part visibility
 - Verify vision job configuration on vision system
 - Confirm camera positioning and focus
@@ -310,12 +335,6 @@ The FANUC GRI client uses a layered architecture:
 - **Background Module**: Compiled KAREL `.pc` (`gri_comm_background.pc`) handling socket/protocol and register bridging
 - **TCP Socket**: Binary protocol communication with vision system
 
-### Pose Frame Behavior
-
-- The background module reads the current robot pose for protocol exchange as base (UF[0]) to flange (UT[0]).
-- Implementation detail: it temporarily saves and sets `$MNUFRAMENUM[1]`/`$MNUTOOLNUM[1]` to `0` only for the `CURPOS(0,0)` call, then restores the previous values immediately. This guarantees a deterministic world→flange pose independent of the active user/tool frames.
-- Future versions may replace this with a math-based conversion that avoids any temporary frame changes.
-
 ## Deployment Checklist
 
 - [ ] `gri_comm_background.pc` loaded
@@ -353,14 +372,25 @@ Integrate GRI error handling with your existing error management:
 
 ```fanuc
 CALL GRI_TRIGGER_JOB_SYNC(1) ;
-SELECT R[150:gri error code] OF
-  CASE(20):
-    CALL PROCESS_OBJECT ;
-  CASE(23):
-    CALL HANDLE_VISION_ERROR ;
-ENDSELECT ;
+IF R[150:gri error code]=0, CALL PROCESS_OBJECT ;
+IF R[150:gri error code]<0, CALL HANDLE_VISION_ERROR ;
+IF R[150:gri error code]>0, CALL HANDLE_NO_POSE_OR_WARNING ;
 ```
 
-Note: In this implementation, a "no object" situation is signaled as `R[150]=23` with `R[151]=13` (no poses found). Consider branching on `R[151]` to distinguish causes of errors if needed.
+Note: A "no object" situation is signaled as `R[150]=1` (NO_POSES_FOUND). Consider branching on `R[151]` for module/vendor specific details when needed.
 
 The system provides consistent, reliable communication with Roboception vision systems while maintaining the familiar FANUC programming environment.
+
+## Protocol Notes (Fixed by Server)
+
+- Protocol: Version 1 (V1)
+- Header: 8 bytes (ASCII "GRI\0", version, length, pose_format, action)
+- Lengths: request 54 bytes, response 80 bytes
+- Job ID: uint16 (LE); Error code: int16 with sign semantics
+- Pose format: EULER_ZYX_B_DEG (26) fixed for FANUC
+  - rot_1 = R (roll/X), rot_2 = P (pitch/Y), rot_3 = W (yaw/Z)
+  - Mapped to XYZWPR in `PR[53]` as R→R, P→P, W→W
+- Scaling: All pose components are int32 scaled by 1e6
+- Job status: returned in `data_2` (mapped to `R[152]`)
+
+See `karel/gri_common_const.kl` for the exact packing/unpacking.
@@ -0,0 +1,58 @@
+/PROG  GRI_EXAMPLE_ASYNC	  Macro
+/ATTR
+OWNER		= MNEDITOR;
+COMMENT		= "Async job example";
+PROG_SIZE	= 1400;
+CREATE		= DATE 25-01-07  TIME 18:00:00;
+MODIFIED	= DATE 25-01-07  TIME 18:00:00;
+FILE_NAME	= ;
+VERSION		= 0;
+LINE_COUNT	= 34;
+MEMORY_SIZE	= 2000;
+PROTECT		= READ_WRITE;
+TCD:  STACK_SIZE	= 0,
+      TASK_PRIORITY	= 50,
+      TIME_SLICE	= 0,
+      BUSY_LAMP_OFF	= 0,
+      ABORT_REQUEST	= 0,
+      PAUSE_REQUEST	= 0;
+DEFAULT_GROUP	= 1,*,*,*,*;
+CONTROL_CODE	= 00000000 00000000;
+/MN
+   1:  !GRI Async Example - Trigger, poll status, fetch pose ;
+   2:  MESSAGE[Starting GRI Async Example] ;
+   3:  ! Standardize frames: UF:0 (world), UT:0 (flange)
+   4:  CALL GRI_SETFRAMES ;
+   5:  !--- Open Communication --- ;
+   6:  CALL GRI_OPEN_COMMUNICATION ;
+   7:  MESSAGE[GRI Communication Started] ;
+   8:  ! Trigger async job with ID 1 ;
+   9:  CALL GRI_TRIGGER_JOB_ASYNC(1) ;
+  10:  IF R[150:gri error code]=0,JMP LBL[10] ;
+  11:  MESSAGE[Async start failed] ;
+  12:  JMP LBL[90] ;
+  13:  LBL[10] ;
+  14:  MESSAGE[Async started OK] ;
+  15:  ! Poll job status until DONE ;
+  16:  LBL[20] ;
+  17:  CALL GRI_GET_JOB_STATUS(1) ;
+  18:  IF R[150:gri error code]<>0,JMP LBL[90] ;
+  19:  IF R[152:gri data 2]=2,JMP LBL[20] ;
+  20:  IF R[152:gri data 2]=4,JMP LBL[90] ;
+  21:  IF R[152:gri data 2]<>3,JMP LBL[20] ;
+  22:  MESSAGE[Job DONE] ;
+  23:  ! Fetch next pose ;
+  24:  CALL GRI_GET_NEXT_GRASP(1) ;
+  25:  IF R[150:gri error code]=0,JMP LBL[30] ;
+  26:  MESSAGE[No pose available] ;
+  27:  JMP LBL[90] ;
+  28:  LBL[30] ;
+  29:  MESSAGE[Pose received - PR[53]] ;
+  30:  LBL[90] ;
+  31:  CALL GRI_QUIT ;
+  32:  MESSAGE[GRI Async Example Failed] ;
+  33:  JMP LBL[100] ;
+  34:  LBL[100] ;
+/POS
+/END
+
@@ -7,7 +7,7 @@ CREATE		= DATE 25-07-10  TIME 18:05:34;
 MODIFIED	= DATE 25-07-10  TIME 18:05:56;
 FILE_NAME	= AAAGRIHE;
 VERSION		= 0;
-LINE_COUNT	= 74;
+LINE_COUNT	= 62;
 MEMORY_SIZE	= 3036;
 PROTECT		= READ_WRITE;
 TCD:  STACK_SIZE	= 0,
@@ -20,77 +20,65 @@ DEFAULT_GROUP	= 1,*,*,*,*;
 CONTROL_CODE	= 00000000 00000000;
 /MN
    1:  !================================ ;
-   2:  ! GRI HAND-EYE CALIBRATION EXAMPL ;
-   3:  ! 8-Pose Calibration for Maximum  ;
-   4:  ! Uses direct positions with touc ;
-   5:  !================================ ;
-   6:   ;
-   7:  !--- INSTRUCTIONS FOR ROBOT PROGR ;
-   8:  MESSAGE[HEC 8-Pose Calibration] ;
-   9:  MESSAGE[Use TOUCHUP on P[1] to P[8]] ;
-  10:  PAUSE ;
-  11:   ;
-  12:  !--- START CALIBRATION PROCESS -- ;
-  13:  MESSAGE[Starting HEC Calibration] ;
-  14:   ;
-  15:  !--- Open Communication --- ;
-  16:  CALL GRI_OPEN_COMMUNICATION    ;
-  17:  MESSAGE[Communication ready] ;
-  18:   ;
-  19:  !--- Initialize HEC Pipeline 0 -- ;
-  20:  MESSAGE[Init HEC Pipeline 0] ;
-  21:  CALL GRI_HEC_INIT(0) ;
-  22:  WAIT R[141:gri_command]=(-1)    ;
-  23:  WAIT    .20(sec) ;
-  24:  MESSAGE[HEC Pipeline ready] ;
-  25:   ;
-  26:  !--- CALIBRATION POSES 1-8 --- ;
-  27:  MESSAGE[Move to Pose 1] ;
-  28:J P[1] 100% FINE    ;
+   2:  ! GRI HEC EXAMPLE ;
+   3:  ! 8-Pose Calibration ;
+   4:  !================================ ;
+   5:  !--- INSTRUCTIONS FOR ROBOT PROGR ;
+   6:  MESSAGE[HEC 8-Pose Calibration] ;
+   7:  MESSAGE[Use TOUCHUP on P[1] to P[8]] ;
+   8:  PAUSE ;
+   9:  !--- START CALIBRATION PROCESS -- ;
+  10:  MESSAGE[Starting HEC Calibration] ;
+  11:  ! Standardize frames: UF:0 (world), UT:0 (flange)
+  12:  CALL GRI_SETFRAMES ;
+  13:  !--- Open Communication --- ;
+  14:  CALL GRI_OPEN_COMMUNICATION    ;
+  15:  MESSAGE[Communication ready] ;
+  16:  !--- Initialize HEC Pipeline 0 -- ;
+  17:  MESSAGE[Init HEC Pipeline 0] ;
+  18:  CALL GRI_HEC_INIT(0) ;
+  19:  WAIT R[141:gri_command]=(-1)    ;
+  20:  WAIT    .20(sec) ;
+  21:  MESSAGE[HEC Pipeline ready] ;
+  22:  !--- CALIBRATION POSES 1-8 --- ;
+  23:  MESSAGE[Move to Pose 1] ;
+  24:J P[1] 100% FINE    ;
+  25:  WAIT   2.00(sec) ;
+  26:  CALL GRI_HEC_SET_POSE(0,1) ;
+  27:  MESSAGE[Move to Pose 2] ;
+  28:J P[2] 100% FINE    ;
   29:  WAIT   2.00(sec) ;
-  30:  CALL GRI_HEC_SET_POSE(0,1) ;
-  31:   ;
-  32:  MESSAGE[Move to Pose 2] ;
-  33:J P[2] 100% FINE    ;
-  34:  WAIT   2.00(sec) ;
-  35:  CALL GRI_HEC_SET_POSE(0,2) ;
-  36:   ;
-  37:  MESSAGE[Move to Pose 3] ;
-  38:J P[3] 100% FINE    ;
-  39:  WAIT   2.00(sec) ;
-  40:  CALL GRI_HEC_SET_POSE(0,3) ;
-  41:   ;
-  42:  MESSAGE[Move to Pose 4] ;
-  43:J P[4] 100% FINE    ;
-  44:  WAIT   2.00(sec) ;
-  45:  CALL GRI_HEC_SET_POSE(0,4) ;
-  46:   ;
-  47:  MESSAGE[Move to Pose 5] ;
-  48:J P[5] 100% FINE    ;
+  30:  CALL GRI_HEC_SET_POSE(0,2) ;
+  31:  MESSAGE[Move to Pose 3] ;
+  32:J P[3] 100% FINE    ;
+  33:  WAIT   2.00(sec) ;
+  34:  CALL GRI_HEC_SET_POSE(0,3) ;
+  35:  MESSAGE[Move to Pose 4] ;
+  36:J P[4] 100% FINE    ;
+  37:  WAIT   2.00(sec) ;
+  38:  CALL GRI_HEC_SET_POSE(0,4) ;
+  39:  MESSAGE[Move to Pose 5] ;
+  40:J P[5] 100% FINE    ;
+  41:  WAIT   2.00(sec) ;
+  42:  CALL GRI_HEC_SET_POSE(0,5) ;
+  43:  MESSAGE[Move to Pose 6] ;
+  44:J P[6] 100% FINE    ;
+  45:  WAIT   2.00(sec) ;
+  46:  CALL GRI_HEC_SET_POSE(0,6) ;
+  47:  MESSAGE[Move to Pose 7] ;
+  48:J P[7] 100% FINE    ;
   49:  WAIT   2.00(sec) ;
-  50:  CALL GRI_HEC_SET_POSE(0,5) ;
-  51:   ;
-  52:  MESSAGE[Move to Pose 6] ;
-  53:J P[6] 100% FINE    ;
-  54:  WAIT   2.00(sec) ;
-  55:  CALL GRI_HEC_SET_POSE(0,6) ;
-  56:   ;
-  57:  MESSAGE[Move to Pose 7] ;
-  58:J P[7] 100% FINE    ;
-  59:  WAIT   2.00(sec) ;
-  60:  CALL GRI_HEC_SET_POSE(0,7) ;
-  61:   ;
-  62:  MESSAGE[Move to Pose 8] ;
-  63:J P[8] 100% FINE    ;
-  64:  WAIT   2.00(sec) ;
-  65:  CALL GRI_HEC_SET_POSE(0,8) ;
-  66:   ;
-  67:  !--- PERFORM CALIBRATION --- ;
-  68:  MESSAGE[All poses set] ;
-  69:  MESSAGE[Calibrating...] ;
-  70:  CALL GRI_HEC_CALIBRATE(0) ;
-  71:  MESSAGE[HEC Complete] ;
-  72:  LBL[99] ;
-  73:  !--- CLEANUP --- ;
-  74:  CALL GRI_QUIT    ;
+  50:  CALL GRI_HEC_SET_POSE(0,7) ;
+  51:  MESSAGE[Move to Pose 8] ;
+  52:J P[8] 100% FINE    ;
+  53:  WAIT   2.00(sec) ;
+  54:  CALL GRI_HEC_SET_POSE(0,8) ;
+  55:  !--- PERFORM CALIBRATION --- ;
+  56:  MESSAGE[All poses set] ;
+  57:  MESSAGE[Calibrating...] ;
+  58:  CALL GRI_HEC_CALIBRATE(0) ;
+  59:  MESSAGE[HEC Complete] ;
+  60:  LBL[99] ;
+  61:  !--- CLEANUP --- ;
+  62:  CALL GRI_QUIT    ;
 /END